Swagger

通过Swagger规范，只需要按照规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

---

Swagger注解内容

Controller层中

类与方法定义说明

@Api 标记一个Controller类作为Swagger文档资源

主要参数

tags：说明该类的作用，参数是个数组，可以填多个。
description = “用户基本信息操作”
value=”该参数没什么意义，在UI界面上不显示，所以不用配置”
格式：tags={“作用1”,”作用2”}

代码示例

@Api(tags={"用户接口"})
@RestController
public class UserController {

}

@ApiOperation 用于方法上，说明方法的作用，每一个接口的定义

主要参数

value=”方法的用途和作用”
notes=”方法的注意事项和备注”
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={“作用1”,”作用2”}
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

方法参数说明

@ApiParam 用于方法的参数说明

主要参数

name=”参数名称”
value=”参数的简要说明”
defaultValue=”参数默认值”
required=”true” 表示属性是否必填，默认为false

代码示例

@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {

}

@ApiImplicitParam 用于方法上，为单独的请求参数进行说明

@ApiImplicitParams 是组装了多个@ApiImplicitParam

主要参数

name=”参数ming”
value=”参数说明”
dataType=”参数数据类型”
paramType=”query” 表示参数放在哪里
· header 请求参数的获取：@RequestHeader
· query 请求参数的获取：@RequestParam
· path（用于restful接口）请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
defaultValue=”参数的默认值”
required=”true” 表示是否必须传递参数

代码示例

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "path", required = true, defaultValue = "1") })
@GetMapping("/user/{id}")
public UserDto getUser(@PathVariable("id") String id) {
    return new UserDto();
}

方法响应说明

@ApiResponse 用于方法上，根据响应码表示不同响应

@ApiResponses 组装多个@ApiResponse

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"   

示例代码

@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {

}

model实体层中

@ApiModel 用于响应实体类，用于说明实体作用

主要参数

value=”model实体类的简要说明”
description=”描述实体的作用”
parent = 类.class 为模型提供父类以允许描述继承关系

@ApiModelProperty 用于属性上，描述实体类属性

主要参数

value=”属性简要说明”
name=”重写属性名称”
required=”true” 是否为必传参数

示例代码

@Data
@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {

    @ApiModelProperty(value = "ID")
    private String id;

    @ApiModelProperty(value = "名称")
    private String name;

    @ApiModelProperty(value = "年龄")
    private int age;

}

---

Swagger 在线测试接口

接口查看地址可以通过 服务地址/swagger-ui.html 来访问

示例

http://localhost:9999/swagger-ui.html#/

---

swagger-ui.html页面导出

将html页面导出为静态文件

​ ASCIIDOC

​ MARKDOWN

​ CONFLUENCE_MARKUP

---

可能需要的步骤

配置setting.xml文件

在本地电脑中idea下载的maven路径中配置setting.xml文件

以本机为例：C:\Users\Matt.m2

文件内容（配置阿里云镜像）

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<mirrors>
    <mirror>
        <id>nexus-aliyun</id>
        <mirrorOf>*</mirrorOf>
        <name>Nexus aliyun</name>
        <url>https://maven.aliyun.com/repository/jcenter</url>
    </mirror>
</mirrors>
</settings>

添加至pom.xml

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.2.0</version>
    <configuration>
        <!--此处端口一定要是当前项目启动所用的端口-->
        <swaggerInput>http://localhost:9999/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated</outputDir>
        <config>
            <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

转换导出文件类型 包含 html pdf

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <!-- Include Asciidoctor PDF for pdf generation -->
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.10.1</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.21</version>
        </dependency>
    </dependencies>
    <!-- Configure generic document generation settings -->
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
    <!-- Since each execution can only handle one backend, run
         separate executions for each desired output type -->
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>src/docs/asciidoc/html</outputDirectory>
            </configuration>
        </execution>

        <execution>
            <id>output-pdf</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
            </configuration>
        </execution>

    </executions>
</plugin>

配置完成过后 执行maven命令

需要配置本机maven环境

以idea为例，Terminal窗口

mvn swagger2markup:convertSwagger2markup

mvn generate-resources