Generating Swagger documentation from existing REST api

Question

Given an existing JAX-RS-annotated API that accepts & returns json, with jackson-annotated types, is there a way that I can generate some YAML Swagger documentation? My plan B is to write some code that uses reflection to find REST-annotated types, make a hashmap of their arguments & returns, and then crawl those classes for Jackson annotations, and generate the documentation that way.

I would prefer to use a solution that already exists to writing a one-off thing. I found this Swagger module that claims it can parse Jackson configurations (https://github.com/FasterXML/jackson-module-swagger) but I don't know enough about Swagger to understand what modules are and whether I can use it to generate Swagger from existing code.

score 1 · Accepted Answer · answered Nov 19 '16 at 10:21

1

You might want to have a look at this project: https://github.com/sdaschner/jaxrs-analyzer

It can generate Swagger documentation automatically for JAX-RS. As far as I know Jackson specific annotations are not taken into consideration.

answered Nov 19 '16 at 10:21

simdevmon

673
7
14

This gives me a starting point for what I'm looking for - I can build on this. Thanks! – Val Akkapeddi Dec 08 '16 at 17:03

score 1 · Answer 2 · answered Nov 21 '16 at 08:41

Swagger will generate interactive documentation for annotated methods. You don't need to write your own crawler. Add lib:

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jaxrs_2.10</artifactId>
        <version>1.3.13</version>
        <scope>compile</scope>
    </dependency>

Configure it:

private void configureSwagger(String swaggerBasePath){
    SwaggerConfig swaggerConfig = new SwaggerConfig();
    ConfigFactory.setConfig(swaggerConfig);
    swaggerConfig.setSwaggerVersion("Version");
    swaggerConfig.setApiVersion("1"); 
    swaggerConfig.setBasePath("http://example.com:8080/your-service");
    ScannerFactory.setScanner(new DefaultJaxrsScanner());
    ClassReaders.setReader(new DefaultJaxrsApiReader());
}

Annotate your service and methods:

@Path("/v1/items")
@Api(value = "/v1/items", description = "API description for Swagger")
public class ItemsService {

      @GET
      @Path("/list")
      @ApiOperation(value = "Get items list", notes = "Returns items list.")
      @Consumes(MediaType.APPLICATION_JSON)
      @Produces(MediaType.APPLICATION_JSON)
      public ItemsResponse getItems(){
          ...
      }

}

Add Swagger UI folder and modify its index.html source to load your REST service documentation URL.

Thanks for the answer, but I was trying to avoid adding the swagger notations & having to carry even more dependencies. :-( — Val Akkapeddi, Dec 08 '16 at 17:10
@Justas: Don't understand what you mean: Where to "add lib"? Where to "configure it"? Where to annotate? - I can't find this in swagger. — Peter, Jan 03 '18 at 17:26
@Peter - I don't understand your question. What build tool do you use? What framework? — Justinas Jakavonis, Jan 03 '18 at 17:35
I can understand both of you (Justas and Peter). I just tried to learn this from and had answers like this. "add lib" (means to your maven pom.xml file add the lines shown). Now the library named swagger-jaxrs_2.10 is available to your web application. I'm not sure if the configure section is run during build time or at run time. I'm guessing it is at run time and somehow updates a Swagger.json file that is read by the SwaggerUI webapp. I'm not sure how this happens either. The annotate service methods is required so the swagger-jaxrs library can know what swagger info to generate. — PatS, Nov 05 '18 at 19:21

Generating Swagger documentation from existing REST api

2 Answers2

Linked