1

I have a small REST service (made with spring) and now I am looking for a solution to automatically generate a schema for this service.

During my research I found some hints of the classes RepositorySchemaController and PersistentEntityToJsonSchemaConverter. But I just want to generate a JSON schema of my REST service. Why I need spring data for that? In this case I am not using any kind of persistence.

In addition I am looking for a comprehensible example to do that.

skaffman
  • 398,947
  • 96
  • 818
  • 769
baymon
  • 459
  • 1
  • 5
  • 20

1 Answers1

2

By schema, I guess that you mean metadata by schema, i.e. all endpoints, exchanged payload structures, path variables, query parameters.

In fact, there are some formats regarding this that provide structures regarding this issue:

  • Swagger2 - see http://swagger.io/. It comes in addition with tools to display graphically a documentation for your RESTful service and to generate both client SDKs and server skeletons.
  • RAML - see http://raml.org/. It also comes with an visual editor.

I think that you should provide content with one (or both) format for your service "schema".

I see two approaches for this:

  • Static one - you generate the content based by introspecting your source code. You can detect classes with annotation Controller, introspect the classes to find out methods with annotations RequestMapping, get parameters and returned classes to determine payload structures, and so on... Spring provides a support to find out from classpath based on specific annotations. See this link for more details: Scanning Java annotations at runtime.

    I think that this approach is acceptable since when you update resources or payload structures, you need to restart your application, so you can regenerate your "schema".

    Based on this generated content, you can add a specific Spring controller to serve it. You can inject a Spring Resource (classpath one) on this file.

  • Dynamic one (at runtime) - Spring provides you a class RequestMappingHandlerMapping that contains all these hints. You can inject it within your "schema" controller and use the return of the method RequestMappingHandlerMapping#getHandlerMethods to build the content. See this link for more details: How to find all controllers in Spring MVC?.

You can notice that APISpark (see this tutorial http://restlet.com/technical-resources/apispark/tutorials/document-restlet-api) provides such introspection mechanism for Restlet applications. This adds an Web API within the APISpark platform and then you can get the corresponding Swagger2 and RAML content. Perhaps could we extend this for Spring MVC / REST applications...

Hope it helps you, Thierry

Community
  • 1
  • 1
Thierry Templier
  • 198,364
  • 44
  • 396
  • 360