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

ゝ一世哀愁。 2021-06-10 20:37 550阅读 0赞

## 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，出现如下界面说明接口文档生成成功。  
![swagger接口文档][swagger]  
6.点击方法列表可以看到该方法的详细信息和进行功能调试。  
![详细信息][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5NjQ1NTA1_size_16_color_FFFFFF_t_70]  
![功能测试][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5NjQ1NTA1_size_16_color_FFFFFF_t_70 1]

[swagger]: /images/20210607/3c588c12b6194e1fa2f9b10338e42a18.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5NjQ1NTA1_size_16_color_FFFFFF_t_70]: /images/20210607/d6b8285fa1f84244bb8a4f41fa6cc62f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5NjQ1NTA1_size_16_color_FFFFFF_t_70 1]: /images/20210607/15d2735e30c146cc9519c39fdf27fcde.png