关于 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 的工具，而且还提供了从规范(v2 中的 swagger.json)生成客户端和服务器代码的功能，此外还有一个很好的 Web 界面来与您的 API 交互.

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

你能给我一些关于它的建议吗?

Could you please give me some recommendations about it?

谢谢

推荐答案

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

只需对您现有的 REST API 进行一些注释，它就会自动为您生成整个 swagger 规范.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 用于您的应用程序类

像这样

@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屋！