SpringBoot--swagger搭建、配置及使用

一、 作用：

1. 接口的文档在线自动生成。

2. 接口测试。

二、模块介绍

Swagger是一组开源项目，其中主要要项目及功能如下：

1、Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

2、Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

3、Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

4、Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

5、Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

三、配置

1、maven配置（版本号请根据实际情况自行更改）

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.2.2</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.2.2</version>

</dependency>

2、创建swagger配置类（在Application.java同级创建Swagger2的配置类Swagger2）

package com.example.demo;

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;

@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("朦胧的夜测试Swagger项目")
                .description("更多请关注 博客园--朦胧的夜")
                .termsOfServiceUrl("https://www.cnblogs.com/liconglong/")
                .contact("lcl")
                .version("1.0")
                .build();
    }

}

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

注意：一定要加上@Configuration和@EnableSwagger2这两个注解，@EnableSwagger2应该是标注该类是Swagger的配置类，@Configuration可以使spring启动就加载该类，如果这两个配置文件不加，则项目启动后，打开Swagger页面后，内容为空。

3、添加文档内容（在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容）

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

l   code：数字，例如400

l   message：信息，例如"请求参数没填好"

l   response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

l   @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

例子：

package com.example.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping("/menglongdeyeController")
@Api(value = "朦胧的夜的测试接口")
public class SwaggerTestController {

    @ResponseBody
    @RequestMapping(value ="/test1", method= RequestMethod.GET)
    @ApiOperation(value="单独一个入参测试接口", notes="接口描述，例如：只能输入‘朦胧的夜’")
    @ApiImplicitParam(paramType="query", name = "blogName", value = "博客名称", required = true, dataType = "String",defaultValue = "朦胧的夜")
    public String test1(@RequestParam String blogName){
        if("朦胧的夜".equals(blogName)){
            return "对了！！！";
        }else{
            return "错了！！！";
        }

    }

    @ResponseBody
    @RequestMapping("/test2")
    @ApiOperation(value="多个入参测试接口", notes="输入用户名密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    public String test2(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
                                 @RequestParam(value="newPassword") String newPassword){
        if(userId <= 0 || userId > 2){
            return "未知的用户";
        }
        if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
            return "密码不能为空";
        }
        if(password.equals(newPassword)){
            return "新旧密码不能相同";
        }
        return "密码修改成功!";
    }

}

四、应用

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.htm

说明：controller一定要加请求类型（post、get等），如果不添加，则会生成7个接口（例如Test2接口），即每个请求类型产生一个接口。

点击接口名称，可进行接口调用测试

输入参数后，点击 Try it out！进行测试，测试结果如下，可查看接口调用状态，如果状态为200（成功），则有相应的返回值等信息。

如上图，可以看到暴漏出来的控制器信息，点击进入可以看到详细信息。

特殊说明一下请求参数为对象时，在POJO上增加@ApiModel(value="学生对象模型")

@ApiModel(value="学生对象模型")
public class Student {
    private String name;
    private String age;
    private String classes;
}

Controller中代码如下：

@ResponseBody
@RequestMapping(value="/student",  method= RequestMethod.POST )
@ApiOperation(value="添加学生信息", notes="")
public Student addDoctor(@RequestBody List<Student> studentList) throws Exception{
    if(studentList == null || studentList.size() == 0){
        throw new Exception("学生集合不允许为空！");
    }
    for (Student student : studentList){
        if(StringUtils.isEmpty(student.getName())){
            throw new Exception("名字不允许为空！");
        }
    }
    return studentList.get(0);
}

使用：

调用：

五、导出接口文档

1、配置

　　pom文件配置插件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档，输出路径
        <outputFile>src/main/doc/ml</outputFile>-->
        <!-- 生成为多个文档，输出路径 -->
        <outputDir>src/main/doc/ml</outputDir>
        <config>
            <!-- wiki格式文档 -->
            <!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
            <!-- ascii格式文档 -->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <!-- markdown格式文档 -->
            <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

配置文件说明

configuration.swaggerInput ：该标签内容需修改为需要导出接口项目的/v2/api-docs 路径
configuration.outputFile ：该标签为生成单个文档指定文档生成路径，如生成txt、md等文件，可随意修改；但注意，该标签与outputDir标签二选一；
configuration.outputDir ：该标签为生成多个文档指定文档目录，如生成ASCIIDOC文件，该类文件可用于结合asciidoctor插件生成html文件；
configuration.config ：该标签内定义的swagger2markup.markupLanguage子标签，只能同时存在一个，如指定生成markdown 即md文件时，就不能指定生成其他类型；
注意：指定生成ASCIIDOC文件类型时，需与configuration.outputDir标签配合使用；

　　2、运行插件（双击运行，即可生成左侧目录中的接口规范文档）

-----------------------------------------------------

后续使用问题及解决：

　　1、使用插件生成离线文档时，提示 swaggerInput 指定的文件找不到

　　　　解决：（1）生成离线文档时，项目必须处于启动状态，否则不能生成

　　　　　　　（2）swaggerInput 指定的地址有可能不太一样，需要调整，具体以swagger页面的地址为准，以下图所示：