关于Swagger API的建议 [英] Advice about Swagger API

问题描述

我正在使用Java 8使用SpringBoot和Spring REST服务构建API，我刚刚发现了Swagger API，现在我想使我的API Swagger兼容.

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.

据我了解，Swagger是记录您的APIS的工具，除了提供与API交互的漂亮Web界面外，还提供了从规范(第2版中的swagger.json)生成客户端和服务器代码的功能.

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.

现在，鉴于我已经具有至少15个控制器的现有API，因此我想对如何进行操作提出一些建议. 我应该从头开始编写整个规范(swagger.json文件)，然后使用codegen生成服务器代码(控制器和对象)吗?还是用Swagger-core注释对现有控制器进行注释，然后从那里生成json规范会更好?

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?

第二种选择对我来说更有意义，但我不知道我们如何从现有API生成swagger.json规范(如果可能).

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

您能给我一些建议吗?

谢谢

推荐答案

将swagger与spring boot或spring cloud集成非常容易.

仅对现有REST API进行一些注释，它将自动为您生成完整的规范. Swagger绝对是最受欢迎的REST API文档框架之一.

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.

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

在springboot应用程序中定义api信息

@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();
}

注释

@EnableSwagger2用于您的应用程序类

Annotations

@EnableSwagger2 for your Application class

类似这样的东西

@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) {

您完成了. Swagger UI是默认包含的，您还可以访问JSON格式的swagger规范.访问http://localhost:12001/swagger-ui.html#/

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#/

有关更多详细信息，请参考此代码库: https://github.com/sanketsw/SpringBoot_REST_API

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

这篇关于关于Swagger API的建议的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！