Investigation of Swagger Documentation Generation

Using Swagger with Spring

1. Add Swagger spring dependency - Swagger2 (https://mvnrepository.com/artifact/io.springfox/springfox-swagger2). Swagger2 dependency, created by Springfox, aids with the auto-generation of documentation based on Swagger metadata provided in your code. The process to do this involves taking all the metadata and generating documentation in various forms - JSON → html. If there is an update to the API, developers will update the metadata ONLY and Swagger tools will generate the documentation.
   
   

   Open

   

2. Enabling Swagger. As we are using Spring, enabling Swagger is as simple as adding an annotation to our code. The "@EnableSwagger2" annotation makes Swagger aware of our Spring application and will generate documentation when our Spring application is started. Swagger will automatically generate a swagger.json file for us at the endpoint localhost:8080/v2/api-docs which includes information about our APIs. In previous reviews, developers seem to manually generate this information and add it to the parent repo under docs.

3. Generating HTML documentation using Swagger-ui. Add Swagger-ui dependency - (https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui). This will provide an endpoint at the root url, which provides the Swagger HTML documentation. This will be located at localhost:8080/swagger-ui.html. Swagger will display the API endpoints which you have configured it to generate documentation for. From here, the user can make the API calls from this location eliminating the need for a separate REST client.
   
   

   Open

   

4. Configuring Swagger. This is necessary to give better descriptions of our APIs in the Swagger generated documentation. Swagger will look for a Spring Bean of type Docket to determine the configuration for generating the various documentations. When creating a Docket instance; the first thing we do is call the select() method on the Docket instance to return a DocketBuilder object in order to build upon our configuration. When we are finished with the DocketBuilder object, we call the build() method on this object to get the prepared Docket object (typical builder pattern). We can configure properties such as the paths in which we wish Swagger to generate documentation for. We can also specify the base package for which we want to generate documentation for. On that built Docket instance we can call the apiInfo method which takes an ApiInfo instance as a parameter. This object takes many arguments such as documentation title, licensing, version, contact information and so on. Once the application is restarted, Swagger will use all of the additional API metadata we have passed in and generate more readable, customizable documentation.
   
   

5. Using Swagger2, we can also add "@ApiOperation" annotations to our code to provide further information about our endpoints; What they are used for? What will be included in the response? etc. Other annotations such as "@ApiParam" allows us to give information about our parameters to be included in the rest call and whether it is required or not.

6. The more information provided to Swagger, the more detailed and informative our generated documentation will be. **TO NOTE** In PF, it looks as though the swagger.json file is generated using Swagger at the (/v1/api-docs/) endpoint and then a file is manually created with the response as the file content and pushed to the parent/docs repo. From here, users can download the swagger.json file and view the UI using a tool such as Swagger Editor.

Generating as part of build

1. Add the Swagger2Markup maven plugin. The convertSwagger2markup goal will generate asciidocs from the Swagger schema definition. (https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup)

2. Add the Asciidoctor Maven Plugin. Asciidoctor will generate the asciidocs into HTML or PDF format. (https://mvnrepository.com/artifact/org.asciidoctor/asciidoctor-maven-plugin)

3. Add support for Spring REST Docs. This will generate the sample code snippets from the tests which will be included in the final documentation.

See for reference: https://hantsy.gitbook.io/build-a-restful-app-with-spring-mvc-and-angularjs/swagger