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.
```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.