SpringBoot如何使用Swagger2生成接口文档

Swagger是什么？

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
Swagger的作用主要有以下两点：

• 接口的文档在线自动生成。
• 功能测试。

在SpringBoot中使用Swagger2生成接口文档

1.引入Swagger2相关依赖。

<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.在Application.java的同级包路径下创建Swagger2的配置类Swagger2。

package com.wunian.swagger;

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;

/**
 * @author wunian
 * @desc Swagger配置类
 *
 * @createdate 2019/9/27
 */
@Configuration  //让spring来加载该类配置
@EnableSwagger2 //启用Swagger2
public class Swagger2 {

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

    /**
     * 创建该API的基本信息
     * 访问地址：http://localhost:8080/swagger-demo/swagger-ui.html
     * @return
     */
    protected ApiInfo createApiInfo(){
        return new ApiInfoBuilder()
                 //标题
                 .title("使用Swagger2来构建SpringBoot Restful APIs")
                 //标题下方的小字
                 .description("详情请关注https://swagger.io/resources/open-api/")
                 //组织服务地址
                 .termsOfServiceUrl("https://swagger.io/resources/open-api/")
                 //开发者
                 .contact("勿念")
                 //API版本
                 .version("0.1")
                 .build();
    }
}

3.创建HelloController，添加Api方法并使用Swagger注解来对文档内容进行相关说明。

package com.wunian.swagger.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;

/**
 * @author wunian
 * @desc 测试Swagger注解的控制器
 * @createdate 2019/9/27
 */
@Controller
@RequestMapping("/hello")
//用在类上，说明该类的作用
@Api(value = "HelloController|一个用来测试swagger注解的控制器")
public class HelloController {

    @ResponseBody
    @RequestMapping(value = "/getUserName",method= RequestMethod.GET)
    //给方法增加说明，notes是补充的说明
    @ApiOperation(value = "根据用户ID获取用户姓名",notes = "userId:1为超级管理员，其他为普通用户")
    //给方法入参增加说明，name：参数名，value：说明参数的意思，dataType：参数类型，required：参数是否必须传
    //paramType：指定参数放在哪个地方，
    //header：请求参数放置于Request Header，使用@RequestHeader获取
    //query：请求参数放置于请求地址，使用@RequestParam获取
    //path：（用于restful接口）-->请求参数的获取：@PathVariable
    //body：（不常用）
    //form（不常用）
    @ApiImplicitParam(paramType = "query",name = "userId",value = "用户ID",dataType = "int")
    public String getUserName(@RequestParam Integer userId){
        if(userId==1){
            return "Admin";
        }else{
            return "普通用户";
        }
    }

    @ResponseBody
    //Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，
    // 否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。
    @RequestMapping("/updatePassword")
    @ApiOperation(value = "修改用户密码",notes = "根据用户ID修改密码")
    //用在方法上包含一组参数说明
    @ApiImplicitParams({
            //如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。
        @ApiImplicitParam(paramType = "query",name = "userId",value = "用户ID",required = true,dataType = "int"),
        @ApiImplicitParam(paramType = "query",name = "pwd",value = "旧密码",required = true,dataType = "String"),
        @ApiImplicitParam(paramType = "query",name = "newPwd",value = "新密码",required = true,dataType = "String")
    })

    public String updatePassword(@RequestParam(value = "userId")Integer userId,
                                 @RequestParam(value = "pwd")String pwd,
                                 @RequestParam(value = "newPwd")String newPwd){
        if(userId<0){
            return "该用户不存在";
        }
        if(StringUtils.isEmpty(pwd)||StringUtils.isEmpty(newPwd)){
            return "密码不能为空";
        }
        if(pwd.equals(newPwd)){
            return "新密码不能和旧密码相同";
        }
        return "密码修改成功";
    }
}

4.在application.properties文件中配置一些基本参数。

#服务端口
server.port=8081
#服务访问的上下文路径
server.servlet.context-path=/
#swagger.json的访问request mapping路径
springfox.documentation.swagger.v2.path=/api-docs

5.启动程序，在浏览器中访问http://localhost:8081/swagger-ui.html，出现如下界面说明接口文档生成成功。

6.点击方法列表可以看到该方法的详细信息和进行功能调试。