介绍

用在前后端分离的项目中，自动生成接口文档。
官网： https://swagger.io/

整和步骤

引入依赖

SpringBoot项目中引入Swagger 的依赖：

<!--依赖管理 -->
    <dependencies>
    	<!--添加Web依赖 -->
        <dependency> 
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!--添加Swagger依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--添加Swagger-UI依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        
        <!--添加热部署依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <!--添加Test依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

添加配置类

即编写swagger启动类SwaggerConfig.java
下面代码中的package、title、version，都可以自己更改。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API列表")
                .version("1.0.0")
                .build();
    }
}

激活Swagger

1，修改添加application.properties文件

#是否激活 swagger true or false
swagger.enable=true

2， 或者 修改添加application-dev.yml文件

swagger:
  enable: true

编写接口文档

即开启spring整合swagger配置

Swagger2 基本使用：

注解说明

具体使用

@Api()
用于类；

参数：
tags：表示说明，tags如果有多个值，会生成多个list
value：用于类描述
hidde：无效果
description：已废用,接口说明

@ApiOperation()
用于方法；

参数：
value：用于方法描述
notes：用于提示内容 
tags：可以重新分组（视情况而用）

@ApiImplicitParam()
用于方法
表示单独的请求参数

@ApiImplicitParams()
用于方法，包含多个 @ApiImplicitParam

参数：
name：参数名
value：参数说明
dataType：数据类型
paramType：参数类型

@ApiResponse

返回参数说明
response：返回的对象信息
code：返回的状态信息
message：返回的文本信息

@ApiModel
用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略

@ApiModelProperty

对象字段说明
value：字段名称
example: 字段说明

@ApiIgnore()
用于类或者方法上，可以不被swagger显示在页面上

Swagger2 使用注解来编写文档：
Swagger2编写接口文档相当简单，只需要在控制层（Controller）添加注解来描述接口信息即可。

例子如下：

@RestController
@RequestMapping("/api/user")
@Api("登录功能")
public class LoginController {

    @RequestMapping("/login")
    @ApiOperation("用户名和密码登录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四", required = true),
            @ApiImplicitParam(name = "password", value = "密码", defaultValue = "123456", required = true)
    })
    public ResultObject login(String username, String password) {
    ...

查阅接口文档

编写文档完成之后，启动当前项目，在浏览器打开：http://localhost:8080/swagger-ui.html
（端口根据自己设置来写）

测试接口

Swagger2的强大之处不仅在于快速生成整洁优雅的RestAPI文档，同时支持接口方法的测试操作（类似于客户端PostMan）。