全面介绍Swagger接口文档工具

一、Swagger是什么？

Swagger是一套开源的API文档工具，它能够为RESTful Services自动生成API文档，还能提供在线API测试功能，并且生成客户端的API SDK。Swagger最初是由Tony Tam在2011年创建的。从那以后，Swagger已经发展成为一个极受欢迎的API文档工具。 Swagger 在其生命周期内经过了许多变化，从Swagger 1.2 到 Swagger 2.0，直到成为 OpenAPI ，而这个变化也可以解释为许多人按照之前的 Apache 2.0 许可证核心创建了该项目。

二、Swagger的核心维度

在 Swagger 之中，有三个核心维度：

Swagger Spec：该规范定义了使用 JSON 或 YAML 的 APIs 描述文件的结构。它支持 RESTful APIs 的描述，使得 RESTful APIs 的定义和使用更加简单和规范。

Swagger Editor：Swagger Editor 是一个用于编辑 Swagger API 设计的工具。通过简单而强大的编辑器，它可以帮助用户轻松创建，编辑和维护 Swagger API 规范。

Swagger UI：Swagger UI 允许用户通过浏览器来交互式的查看和试验 API 文档。 用户可以通过一个界面来测试 API 的各个端点，而不需要终端或第三方应用程序支持。

三、如何使用Swagger?

下面我们将介绍如何在Spring Boot应用程序中使用Swagger。

1. 添加Swagger依赖项

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>
 
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>

2. 启用Swagger

启用Swagger 需要添加@Configuration注解，以便将Swagger添加为一个 Spring Bean。这可以通过在应用程序中创建 @Bean 声明方式来完成。

package com.example.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3. 使用Swagger来注释APIs

上面的配置让你能够查看你 Spring Boot 项目中的所有 API 列表，但是如果你想为 API 添加更多的描述、tags 和请求示例，那就需要添加更多的注释了。简单地把Swagger扫描过的范围配置在所有@RequestMapping注解的方法上，并在注解中描述每个特定的API。

@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public User getUserById(@PathVariable(value = "id") Long id) {
        // ...
    }

    @ApiOperation(value = "添加用户", notes = "根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public String addUser(@RequestBody User user) {
        // ...
    }
}

四、Swagger界面展示与说明

Swagger UI 是 Swagger 最突出的特点之一。它提供了一个易于使用 Web 接口来查看、测试和文档化 API。Swagger UI 是Swagger规范的 HTML/CSS/JavaScript 体现形式。因此，您可以将这个界面引入到您的现有项目中，以测试您的 API。

最常见的 Swagger UI 是内置在 Swagger-editor 工具中提供的 UI。该 UI 允许您可视化定义您的 API 并文档化您的 API 存储库。

通过在 Web 浏览器中导航到 Swagger UI 项目并选择并输入一个 OpenAPI（以 Swagger 2.0兼容体验） 规范注册表，您可以将Swagger UI 与您的 API 对接，从而创造一个互动式的 API 文档和操作界面。

效果如图所示：

<img src="https://img-blog.csdn.net/20171025225006921?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvZ3Vvb25nZW43MjUx/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/q/75"
  alt="SwaggerUI"
  title="SwaggerUI"
  style="display:block;margin:auto;width:80%;">