springboot 集成 swagger 以及swagger 常用注解

淩亂°似流年 2023-02-08 12:44 11阅读 0赞

springboot集成swagger的步骤  
注意:  
版本 springboot (2.5.x), springfox-swagger2 (2.5.0)

# 1.引入jar包 #

springboot的版本

<parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.5.8</version>
            <relativePath/> 
        </parent>

swagger2的版本

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

# 2.开启配置 #

在springboot的启动类上加@EnableSwagger2

@SpringBootApplication
    @Configuration
    @EnableSwagger2
    public class DemoApplication {
        
        public static void main(String[] args) {
        
            SpringApplication.run(DemoApplication.class, args);
        }
    }

# 3.在浏览器请求http://localhost:8080/swagger-ui.html #

就会看到swagger的默认页面  
![image.png][]

如果项目的包路径合理，集成swagger到这就完成。。。

# 4.自定义一些配置 #

## 4.1 配置 “标题” “描述” “版本”等展示信息 ##

展示结果  
![image.png][image.png 1]

## 4.2 配置 扫描包路径 分组 url路径过滤等 ##

@Configuration
    public class SwaggerConfig {
        
        /**
         * 自定义ApiInfo的信息
         *
         * @return ApiInfo
         */
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("demo-api") // 设置标题
                    .description("用于测试的服务api列表") // 设置描述
                    .version("1.1.0") // 设置版本
                    .build();
        }
    
        /**
         * 创建一个Docket 并注入一个Docket实例
         *
         * @return Docket
         */
        @Bean
        public Docket docket() {
        
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
    
        /**
         * 创建一个Docket 并注入一个Docket实例 多个Docket实例就是多个组
         *
         * @return Docket
         */
        @Bean
        public Docket docket2() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("测试接口") // 指定组名
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 指定扫描的包
                    .paths(PathSelectors.ant("/test/**")) // 展示满足url格式的路径
                    .build();
        }
    }

展示结果  
![image.png][image.png 2]

# 5 常用的注解 #

@Api  
@ApiOperation  
@ApiModel  
@ApiModelProperty  
@ApiParam  
@ApiResponse  
@ApiResponses  
@ResponseHeader

## 5.1 @Api ##

位置：类  
作用：描述或者说明该类的作用， 一般用于标记Controller  
参数：

使用示例:

@Api(value = "/", hidden = true, tags = {
        "tag1", "tag2"}, description = "description")
    public class TestConfigController {
        }

页面展示  
![image.png][image.png 3]

## 5.2 @ApiOperation() ##

位置：方法  
作用：说明一个http请求访问该方法的操作  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>url的路径值</td> 
  </tr> 
  <tr> 
   <td>tags</td> 
   <td>如果设置这个值、value的值会被覆盖</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>注意事项</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>对api资源的描述</td> 
  </tr> 
  <tr> 
   <td>basePath</td> 
   <td>基本路径可以不配置</td> 
  </tr> 
  <tr> 
   <td>position</td> 
   <td>如果配置多个Api 想改变显示的顺序位置</td> 
  </tr> 
  <tr> 
   <td>produces</td> 
   <td>For example, “application/json, application/xml”</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>For example, “application/json, application/xml”</td> 
  </tr> 
  <tr> 
   <td>protocols</td> 
   <td>Possible values: http, https, ws, wss.</td> 
  </tr> 
  <tr> 
   <td>authorizations</td> 
   <td>高级特性认证时配置</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>配置为true 将在文档中隐藏</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>返回的对象</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>这些对象是有效的 “List”, “Set” or “Map”.，其他无效</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”</td> 
  </tr> 
  <tr> 
   <td>code</td> 
   <td>http的状态码 默认 200</td> 
  </tr> 
  <tr> 
   <td>extensions</td> 
   <td>扩展属性</td> 
  </tr> 
 </tbody> 
</table>

使用示例:

@ApiOperation(value="测试配置", notes = "注意事项", httpMethod = "GET", hidden = false)
        @GetMapping("/testConfig")
        public Object testConfig() {
            return null;
        }

页面展示  
![image.png][image.png 4]

## 5.3 @ApiModel ##

位置：类  
作用：用于实体类上，用于说明实体的作用  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>说明方法的用途和作用</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>描述实体的作用</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>注意事项</td> 
  </tr> 
  <tr> 
   <td>parent</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>discriminator</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>subTypes</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>reference</td> 
   <td></td> 
  </tr> 
 </tbody> 
</table>

## 5.4 @ApiModelProperty ##

位置：类属性  
作用：用于实体类上，用于说明实体的作用  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>属性在文档中的说明</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>属性在文档中的展示名称</td> 
  </tr> 
  <tr> 
   <td>allowableValues</td> 
   <td>允许的值</td> 
  </tr> 
  <tr> 
   <td>access</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>注意事项</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>数据类型</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>default false;</td> 
  </tr> 
  <tr> 
   <td>position</td> 
   <td>如果配置多个Api 想改变显示的顺序位置</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>配置为true 将在文档中隐藏</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>readOnly</td> 
   <td>default false;</td> 
  </tr> 
  <tr> 
   <td>reference</td> 
   <td></td> 
  </tr> 
 </tbody> 
</table>

使用示例：

@ApiModel(value = "用户", description = "用户实体")
    public class User {
        @ApiModelProperty(value = "主键")
        private Integer id;
        @ApiModelProperty(value = "用户名称")
        private String name;
        @ApiModelProperty(value = "用户年龄", notes = "年龄的值需要符合实际1~200")
        private Integer age;
    }

页面展示：  
![image.png][image.png 5]

## 5.5 @ApiParam ##

位置：方法参数，方法， 属性  
作用：用于说明参数  
参数:

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>属性名称，对应页面上参数名称</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>属性值，对应页面的参数描述</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>默认属性值</td> 
  </tr> 
  <tr> 
   <td>allowableValues</td> 
   <td>可以不配置</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否属性必填</td> 
  </tr> 
  <tr> 
   <td>access</td> 
   <td>不过多描述</td> 
  </tr> 
  <tr> 
   <td>allowMultiple</td> 
   <td>默认为false</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>隐藏该属性</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>举例子</td> 
  </tr> 
 </tbody> 
</table>

使用示例:

public User testConfig(@RequestBody @ApiParam(value = "用户", name = "user", required = true) User user) {
        
            user.setId(0);
            return user;
        }

页面展示：  
![image.png][image.png 6]

## 5.6 @ApiResponse ##

位置：方法  
作用：配置响应说明  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>code</td> 
   <td>http的状态码</td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>默认响应类 Void</td> 
  </tr> 
  <tr> 
   <td>reference</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
  <tr> 
   <td>responseHeaders</td> 
   <td>参考 ResponseHeader 属性配置说明</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
 </tbody> 
</table>

## 5.7 @ApiResponses ##

位置：方法，类  
作用：配置响应说明集  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>多个ApiResponse配置</td> 
  </tr> 
 </tbody> 
</table>

使用示例:

@ApiResponses(value = {
        
                @ApiResponse(code=404, message = "请求路径有错误"),
                @ApiResponse(code=500, message = "方法异常")
        })
        @PostMapping("/testConfig")
        public User testConfig(@RequestBody @ApiParam(value = "用户", name = "user", required = true) User user) {
        
            user.setId(0);
            return user;
        }

页面展示：  
![image.png][image.png 7]

## 5.8 @ResponseHeader ##

位置：方法  
作用：配置响应头  
参数：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>响应头名称</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>头描述</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>默认响应类 Void</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
 </tbody> 
</table>

使用示例:

@ResponseHeader(name = "head1", description = "测试配置的响应头",response = User.class)
        @PostMapping("/testConfig")
        public User testConfig(@RequestBody @ApiParam(value = "用户", name = "user", required = true) User user) {
        
            user.setId(0);
            return user;
        }

[image.png]: /images/20230208/cba0cf13a3f044e985757888b45be26e.png
[image.png 1]: /images/20230208/3b00f84913dd4e298825e1ae75025aea.png
[image.png 2]: /images/20230208/ac3703b58d0548f8bab5d60121aa78e6.png
[image.png 3]: /images/20230208/c9582f6fbe1b4ffc837603160984f788.png
[image.png 4]: /images/20230208/663898893ece4ddda731daa5dfa26a3a.png
[image.png 5]: /images/20230208/1ec96f1e1b61458982e45d36d6ad1a7c.png
[image.png 6]: /images/20230208/d0f488dbd9b34060828326c13c8eceab.png
[image.png 7]: /images/20230208/6d3ba717e56245439c2370275ac4d585.png