Advice about Swagger API

问题:

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

回答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

回答2:

I realise this is late in coming, but here's an alternative for you to consider: instead of generating the OpenAPI API description from your implementation, you could hand-write the OpenAPI API description, then have your implementation read it at startup time and automatically configure its URL routing, response types etc accordingly.

Ie generate the implementation from the documentation, rather than generating documentation from the implementation.

I've no idea how feasible this would be in Spring (sorry). It wasn't difficult with Python and WSGI.

Whether this is a good idea or not is a judgement call only you can make.