SpringBoot整合Swagger2实现在线生成接口文档

旧城等待， 2022-01-16 15:19 353阅读 0赞

*  源码获取

**GitHub：https://github.com/291685399/springboot-learning/tree/master/springboot-swagger201**

*  pom.xml文件添加依赖

<dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.7.0</version>
    </dependency>
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.7.0</version>
    </dependency>
    <dependency>
       <groupId>repos.io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.7.0</version>
    </dependency>

*  配置Swagger2

创建Swagger2Config配置文件

@Configuration
    public class Swagger2Config { 
       @Bean
       public Docket createRestApi() { 
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.wyj.controller"))//包的路径
                   .paths(PathSelectors.any())
                   .build();
       }
       @Bean
       public ApiInfo apiInfo() { 
           return new ApiInfoBuilder()
                   .title("API文档")//接口文档主题
                   .description("API网关接口")//地址
                   .termsOfServiceUrl("www.baidu.com")//路径
                   .version("1.0.0")//版本号
                   .build();
       }
    }

*  在启动类中添加注解用于开启Swagger2

@EnableSwagger2

*  在Controller接口上配置接口参数信息

例子一：

@ApiOperation("根据用户id查询用信息")
    @ApiImplicitParams({ 
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "int", paramType = "query")
    })
    @RequestMapping(value = "/findById", method = RequestMethod.GET)
    public String findById(int id) { 
        return "{'id':'1','username':'zhangsan','password':'123'}";
    }

例子二：

@ApiOperation("根据用户名查询用信息")
    @ApiImplicitParams({ 
            @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "query")
    })
    @RequestMapping(value = "/findByUserName", method = RequestMethod.POST)
    public String findByUsername(String username) { 
        return "{'id':'2','username':'lisi','password':'456'}";
    }

*  访问Swagger2

**浏览器输入：http://127.0.0.1:8080/swagger-ui.html**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70]  
**点击demo-controller（这是上面两个例子的类名）张开**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 1]  
**点击接口，查看接口详细信息**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 2]  
**在Swagger2中可以在线调用接口，填写好需要的参数，点击Try it out即可（我这里findById这个接口id这个参数是请求中必须有的，在注解@ApiImplicitParam中已经定义了required = true）**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 3]

*  最后，加上Swagger2常用注解说明：

> @Api：修饰整个类，描述Controller的作用  
> @ApiOperation：描述一个类的一个方法，或者说一个接口  
> @ApiParam：单个单数描述  
> @ApiModel：用对象来接收参数  
> @ApiProperty：用对象接收参数时，描述对象的一个字段  
> @ApiResponse：HTTP响应其中一个描述  
> @ApiResponses：HTTP响应整体描述  
> @ApiIgnore：使用该注解忽略这个API  
> @ApiError：发生错误返回的信息  
> @ApiImplicitParam：一个请求参数  
> @ApiImplicitParams：多个请求参数

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70]: /images/20220114/122014a767f2474cb898a0f639eb3c4f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 1]: /images/20220114/54264448e1cc4f1499bb6fd31f47f2be.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 2]: /images/20220114/f51c6f5e4f8a49a9abf944e5f2215d42.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1NjIwNTAx_size_16_color_FFFFFF_t_70 3]: /images/20220114/c4932dc449e34c89866572c08ec84de8.png