Advice about Swagger API

Question

I'm building an API using SpringBoot and Spring REST services using Java 8. I've just discovered Swagger API and now I would like to make my API Swagger compliant.

As far I read, Swagger is a tool to document your APIS, but also provides functionalities to generate the client and server code from an specification (swagger.json in v2), besides of a nice web interface to interact with your API.

Now, I would like some recommendations about how to proceed, given that I already have an existing API with at least 15 controllers. Should I write the whole spec from scratch (the swagger.json file) and then use codegen to generate the server code (controllers and objects)? Or would be better to annotate the existing controllers with Swagger-core annotations, and then generate a json spec from there?

The second choice makes more sense to me but I don't know how we generate the swagger.json spec from the existing API (if possible).

Could you please give me some recommendations about it?

Thanks

Answer 1

Integrating swagger with spring boot or spring cloud is very easy.

Only a few annotations to your existing REST APIs and it will generate whole swagger specification for you automatically. Swagger is definitely one of the most popular REST API documentation frameworks.

pom.xml dependencies

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
    <scope>compile</scope>
</dependency>

define api info in your springboot application

@Bean
public Docket newsApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("springboot")
            .apiInfo(apiInfo())
            .select()
            .paths(regex("/.*"))
            .build();
}
 
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("SpringBoot REST API with Swagger")
            .description("SpringBoot REST API with Swagger")
            .termsOfServiceUrl("http://www-03.ibm.com/software/sla/sladb.nsf/sla/bm?Open")
            .contact("sanket**@au1.ibm.com")
            .license("Apache License Version 2.0")
            .licenseUrl("https://github.com/IBM-Bluemix/news-aggregator/blob/master/LICENSE")
            .version("2.0")
            .build();
}

Annotations

@EnableSwagger2 for your Application class

Annotate your REST APIs

Something like this

@RequestMapping(value = "/operate/add/{left}/{right}", method = RequestMethod.GET, produces = "application/json")
@ApiOperation(value = "addNumbers", nickname = "addNumbers")
@ApiResponses(value = { @ApiResponse(code = 200, message = "Success", response = Result.class),
        @ApiResponse(code = 401, message = "Unauthorized"), 
        @ApiResponse(code = 500, message = "Failure") })
public Result add(@PathVariable("left") int left, @PathVariable("right") int right) {

You are done. The Swagger UI is included by default and you can also access the swagger specs in JSON format. Access http://localhost:12001/swagger-ui.html#/

Refer to this code base for more details: https://github.com/sanketsw/SpringBoot_REST_API