diff --git a/_posts/2016-04-05-generate-swagger.md b/_posts/2016-04-05-generate-swagger.md index abec152..fde62b5 100644 --- a/_posts/2016-04-05-generate-swagger.md +++ b/_posts/2016-04-05-generate-swagger.md @@ -32,7 +32,7 @@ Note: please make sure to set the jar version to the latest one available, so th In order to hook up swagger-core in the application, there are multiple solutions, the easiest of which is to just use a custom `Application` subclass. - +```java public class SwaggerTestApplication extends Application { public SwaggerTestApplication() { @@ -58,7 +58,7 @@ In order to hook up swagger-core in the application, there are multiple solution } } - +``` Once this is done, you can access the generated `swagger.json` or `swagger.yaml` at the location: `http(s)://server:port/contextRoot/swagger.json` or `http(s)://server:port/contextRoot/swagger.yaml`. Note that the `title` element for the API is mandatory, so a missing one will generate an invalid swagger file. Also, any misuse of the annotations will generate an invalid swagger file. Any existing bugs of swagger-core will have the same effect. @@ -67,7 +67,7 @@ In order for a resource to be documented, other than including it in the list of A special case, that might give you some head aches, is the use of subresources. The REST resource code usually goes something like this: - +```java @Api @Path("resource") public class Resource { @@ -118,7 +118,7 @@ A special case, that might give you some head aches, is the use of subresources. return "POST " + subresourceName + something; } } - +``` The swagger parser works like a charm if it finds the @Path and @GET and @POST annotations where it thinks they should be. In the case depicted above, the subresource is returned from the parent resource and does not have a @Path annotation at the class level. A lower version of swagger-core will generate an invalid swagger file, so please use the latest version for a correct code generation. If you want to make you life a bit harder and you have a path that goes deeper, something like /resource/{subresource}/{subsubresource}, things might get a bit more complicated. @@ -146,7 +146,7 @@ In the Subresource class, you might have a @PathParam for holding the value of t In order to fix this, use `@ApiParam(hidden=true)` for the subresource `@PathParam` in the `Subsubresource` class. See below. - +```java @Api public class SubSubResource { @@ -171,6 +171,6 @@ In order to fix this, use `@ApiParam(hidden=true)` for the subresource `@PathPar return "POST " + subresourceName + "/" + subsubresourceName + " " +something; } } - +``` There might be more tips and tricks that you will discover once you start using the annotations for your API, but it will not be a slow learning curve and once you are familiar with swagger (both spec and core) you will be able to document your API really fast.