超详细 使用swagger自动生成Api文档swagger-ui

介绍

        这里是一些介绍，如果想直接看如何使用，请直接跳过这部分。但如果有时间，就姑且看一下吧，这部分大概用时3分钟。

swagger是什么？

        Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

        目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。

        swagger就是帮你写接口说明文档的。更具体地，可以看下面的图片，swagger官方建议使用下面的红字部分，这篇博客主要是记录如何，使用swagger自动生成Api文档的，所以只介绍swagger-ui，其他的…以后我用到会再整理。

swagger-ui

        用来显示API文档的，不可编辑，会根据我们在代码中的设置来自动生成Api说明文档。生成的api文档如下，不好意思，长得不太像文档…但比文档更清楚对不对！对！

        本文中的举例全部基于spring boot，如果不太熟悉构建请移步：spring教程（一），既然写道这里，介绍一下项目需要的环境

• 编译器：IntelliJ IDEA 2018.3.5 x64
• 框架：spring-boot-cli-1.4.3.RELEASE-bin
• swagger版本：springfox-swagger2，2.9.2

使用swagger-ui

        通过第一部分“简单使用”能够让你快速地使用swagger-ui来生成api文档，之后会详细地解释swagger-ui一些注解及使用方法。如果想要看swagger-ui用到的一些注解的详细使用方法、说明、及示例请移步第二部分“swagger api注解”。

简单使用

        以下操作基于spring教程（一）的项目内容，项目结构如下，比较简单。

        简单地使用swagger-ui只需要三步。

第一步，配置pom文件。在pom文件中引入swagger的相关依赖，在“<dependencies></dependencies>”中间添加下面的依赖。     

<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.8.0</version>
</dependency>

        第二步，构建swagger配置类。我选择构建的位置是主目录下，目录并不会对运行结果产生影响，但整个项目只能有一个swagger配置类。配置类的代码如下，建议只粘贴类的代码部分，然后“alter+Enter”添加引入的包的部分。

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * Swagger使用的配置文件
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }
 
    //基本信息的配置，信息会在api文档上显示
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("zg测试的接口文档")
                .description("xx相关接口的文档")
                .termsOfServiceUrl("http://localhost:8080/hello")
                .version("1.0")
                .build();
    }
}

        这里需要对第二步说明几点：

• apiInfo：api基本信息的配置，信息会在api文档上显示，可有选择的填充，比如配置文档名称、项目版本号等
• apis：使用什么样的方式来扫描接口，RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式，其他方法我们后续介绍。
• path：扫描接口的路径，PathSelectors下有四种方法，我们这里是全扫，其他方法我们后续介绍。

        第三步，在接口文件中增加对应注解。代码如下，由于我们第二步选择扫描接口的方式是在类前添加@Api；@ApiOperation用于注明接口，value是接口的解释；@ApiParam注解函数里面的参数，name一般与参数名一致，value是解释，required是是否参数必须。

@Controller
@Api
public class HelloController {
    @ApiOperation(value = "你好")
    @ResponseBody
    @PostMapping("/hello")
    public String hello(@ApiParam(name="name",value="对话人",required=true)String name){
        return name+", hello";
    }
}

        上面操作都完成后，在浏览器中输入网址：http://localhost:8080/swagger-ui.html，我使用的接口是默认的8080，具体以自己项目的配置为准。

        swagger api注解

        这一部分除了，下面列出的注解外，还包括上面所介绍的RequestHandlerSelectors和PathSelectors的几种方法及含义。

 @Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息

本文参考：
超详细 swagger api注解
spring boot项目中使用swagger2
5分钟了解swagger
官方Class RequestHandlerSelectors文档