kidwellj/findcommonground.uk
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Update 2016-04-05-generate-swagger.md

Browse source
This commit is contained in:
Teodora Onaca 2016-04-05 12:11:53 +02:00
parent 4e54bc8b48
commit c7302ca93c
1 changed files with 6 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
_posts/2016-04-05-generate-swagger.md
View file

@ -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. 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 class SwaggerTestApplication extends Application {
public SwaggerTestApplication() { 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`. 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. 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: 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 @Api
@Path("resource") @Path("resource")
public class 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; 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. 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. In order to fix this, use `@ApiParam(hidden=true)` for the subresource `@PathParam` in the `Subsubresource` class. See below.
```java
@Api @Api
public class SubSubResource { 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; 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. 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.