swagger2配置及注释详解

曾经终败给现在 2024-05-25 17:36 6阅读 0赞

前面我们记录了如何整合swagger2插件，本篇主要介绍插件的配置及注释说明。

## Swagger2配置文件说明 ##

直接上加了注释的代码，看代码更清晰：

@Configuration
    //@EnableSwagger2
    public class SwaggerConfig {
        
        @Bean
        public Docket systemManagerApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                //获取接口信息
                .apiInfo(getApiInfo())
                //指定主机域名
                .host("https://www.baidu.com/")
                //分组
                .groupName("systemManager")
                .select()
                //-------- 指定扫描那些接口 --------
                //扫描所有
                //.apis(RequestHandlerSelectors.any())
                //扫描所有有注解的api
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //扫描指定位置
                .apis(RequestHandlerSelectors.basePackage("stu.up2uper.springstu.controller"))
                //-------- 指定扫描路径 --------
                .paths(PathSelectors.any())
                .build();
        }
    
        @Bean
        public Docket systemAppApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                //获取接口信息
                .apiInfo(getApiInfo())
                //分组
                .groupName("systemApp")
                .select()
                //-------- 指定扫描那些接口 --------
                //扫描所有
                //.apis(RequestHandlerSelectors.any())
                //扫描所有有注解的api
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //扫描指定位置
                .apis(RequestHandlerSelectors.basePackage("stu.up2uper.springstu.controller"))
                //-------- 指定扫描路径 --------
                .paths(PathSelectors.any())
                .build();
        }
    
        private ApiInfo getApiInfo() {
        
            return new ApiInfoBuilder()
                //标题
                .title("系统接口文档")
                //描述
                .description("此文档为系统接口说明，配置及相关注解")
                //许可证
                .license("Swagger api 2022/16/01")
                //许可证地址
                .license("https://www.github.com")
                //服务条款地址
                .termsOfServiceUrl("https://www.spring.io")
                //版本
                .version("1.0.0")
                //维护人信息
                .contact(new Contact("hunkxia", "https://blog.csdn.net/hunkxia", "hunk.xia@gmail.com"))
                .build();
        }
    
        @Bean
        public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        
            List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
            Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
            allEndpoints.addAll(webEndpoints);
            allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
            allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
            String basePath = webEndpointProperties.getBasePath();
            EndpointMapping endpointMapping = new EndpointMapping(basePath);
            boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
            return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
        }
    
        private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        
            return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
        }
    }

通过配置，我们可以对接口进行分组展示，并且能指定扫描路径，最后呈现的UI如下：

![在这里插入图片描述][285cc8a3d73a4420ac24573928045674.jpeg_pic_center]

## 常见注释说明及用法 ##

swagger2内置了许多注释，来方便开发人员实现接口注释功能，常见注释标签如下：

![在这里插入图片描述][2d0596be547644319591fa05609735b6.jpeg_pic_center]  
其中一些标签的参数都已过时，以下只展示常见标签的说明：

<table> 
 <thead> 
  <tr> 
   <th>标签</th> 
   <th>使用位置</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>Controller</td> 
   <td>请求类说明</td> 
  </tr> 
  <tr> 
   <td>@ApiIgnore</td> 
   <td>Controller</td> 
   <td>隐藏说明，无需参数</td> 
  </tr> 
  <tr> 
   <td>@ApiParam</td> 
   <td>Method</td> 
   <td>方法参数说明</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>Method</td> 
   <td>方法单个参数说明</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>Method</td> 
   <td>方法参数的说明</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse</td> 
   <td>Method</td> 
   <td>单个返回状态码说明</td> 
  </tr> 
  <tr> 
   <td>@ApiResponses</td> 
   <td>Method</td> 
   <td>方法返回状态码说明</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>Model</td> 
   <td>实体类说明</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>Model属性</td> 
   <td>实体类属性说明</td> 
  </tr> 
  <tr> 
   <td>@JsonIgnore</td> 
   <td>Model属性</td> 
   <td>隐藏说明</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>Method</td> 
   <td>方法说明</td> 
  </tr> 
 </tbody> 
</table>

*  @api标签说明：

<table> 
 <thead> 
  <tr> 
   <th>标签</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>tags</td> 
   <td>标题描述，支持多个标题</td> 
  </tr> 
  <tr> 
   <td>produces</td> 
   <td>生产者，输出什么内容，如"application/json, application/xml"</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>消费者，输入什么内容，如上</td> 
  </tr> 
  <tr> 
   <td>protocols</td> 
   <td>请求协议规则</td> 
  </tr> 
  <tr> 
   <td>authorizations</td> 
   <td>安全设置</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>是否隐藏</td> 
  </tr> 
 </tbody> 
</table>

*  @ApiParam标签说明：

一般写在方法参数上如下：

@RequestMapping(value = "listByPage", method = RequestMethod.GET)
    @ResponseBody
    public List<G2AdminRoleAccess> getRolesByPage(
            @ApiParam(value = "页码") @RequestParam(value = "page", defaultValue = "1") int page,
            @RequestParam(value = "size", defaultValue = "10") int size){
        
        return roleAccessService.listRole(page, size);
    }

具体参数

<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>allowMultiple</td> 
   <td>是否为集合</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数数据类型，int、float、String等等</td> 
  </tr> 
  <tr> 
   <td>dataTypeClass</td> 
   <td>参数指定类类型</td> 
  </tr> 
  <tr> 
   <td>paramType</td> 
   <td>参数类型，包括path、query、body、header、form</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>举例</td> 
  </tr> 
  <tr> 
   <td>Example</td> 
   <td>实体类举例</td> 
  </tr> 
  <tr> 
   <td>allowEmptyValue</td> 
   <td>是否可为空</td> 
  </tr> 
  <tr> 
   <td>readOnly</td> 
   <td>是否只读</td> 
  </tr> 
 </tbody> 
</table>

*  @ApiImplicitParam标签说明：

与上方ApiParam一样，只不过注释的位置不一样，如下：

*  @ApiImplicitParams标签说明：

包括多个ApiImplicitParam整合，不再描述，直接给个列子:

@RequestMapping(value = "listAll", method = RequestMethod.GET)
    @ResponseBody
    @ApiImplicitParams({
        
        @ApiImplicitParam()
    })
    public List<G2AdminRoleAccess> getRoles(){
        
        return roleAccessService.listAllRole();
    }

*  @ApiResponse标签说明：

用于描述返回值状态码，主要的参数如下：

<table> 
 <thead> 
  <tr> 
   <th>标题</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>code</td> 
   <td>返回码</td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>返回消息</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>抛出异常的类</td> 
  </tr> 
  <tr> 
   <td>responseHeaders</td> 
   <td>定义响应头</td> 
  </tr> 
 </tbody> 
</table>

参考如下：

@RequestMapping(value = "listAll", method = RequestMethod.GET)
    @ResponseBody
    @ApiImplicitParams({
        
        @ApiImplicitParam()
    })
    @ApiResponse(code = 200, message = "返回正常")
    public List<G2AdminRoleAccess> getRoles(){
        
        return roleAccessService.listAllRole();
    }

*  @ApiResponses标签说明：

支持多个ApiResponse标签。

@RequestMapping(value = "addRole", method = RequestMethod.POST)
    @ApiImplicitParam(name = "role", value = "权限信息", dataTypeClass = G2AdminRoleAccess.class, required = true)
    @ApiResponses({
        
        @ApiResponse(code = 200, message = "返回正常"),
        @ApiResponse(code = 404, message = "请求路径不存在"),
    })
    public int addRole(@RequestBody G2AdminRoleAccess role){
        
        return roleAccessService.addRole(role);
    }

*  @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>parent</td> 
   <td>所属父类</td> 
  </tr> 
 </tbody> 
</table>

@ApiModel(value = "用户角色", description = "用户角色信息")
    public class G2AdminRoleAccess implements Serializable {
        
    }

*  @ApiModelProperty模型属性标签：

<table> 
 <thead> 
  <tr> 
   <th>标签</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>标题</td> 
  </tr> 
  <tr> 
   <td>allowableValues</td> 
   <td>可允许值</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>数据类型</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否必须</td> 
  </tr> 
  <tr> 
   <td>position</td> 
   <td>排序位置</td> 
  </tr> 
  <tr> 
   <td>readOnly</td> 
   <td>是否只读</td> 
  </tr> 
  <tr> 
   <td>allowEmptyValue</td> 
   <td>是否为空</td> 
  </tr> 
 </tbody> 
</table>

举例：

@ApiModel(value = "用户角色", description = "用户角色信息")
    public class G2AdminRoleAccess implements Serializable {
        
        private Integer id;
    
        /**
         * 角色ID
         *
         * @mbg.generated
         */
        @ApiModelProperty(value = "角色ID")
        private Integer roleId;
    }

*  @JsonIgnore标题说明：

与ApiModelProperty标签中的hidden类似，无参数，表示隐藏此属性。

*  @ApiOperation标签说明：

此标签主要用来描述方法的具体说明，主要有以下参数：

<table> 
 <thead> 
  <tr> 
   <th>标签</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>对方法简单说明</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>对方法详细说明</td> 
  </tr> 
  <tr> 
   <td>tags</td> 
   <td>标题，支持多组标题</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>响应容器</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>请求方法类型</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>是否隐藏此方法</td> 
  </tr> 
  <tr> 
   <td>code</td> 
   <td>状态码</td> 
  </tr> 
  <tr> 
   <td>produces</td> 
   <td>生产者，输出格式，如application/json, application/xml</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>消费者，输入格式</td> 
  </tr> 
 </tbody> 
</table>

代码如下：

@RequestMapping(value = "listAll", method = RequestMethod.GET)
    @ResponseBody
    @ApiImplicitParams({
        
        @ApiImplicitParam()
    })
    @ApiOperation(value = "获取角色所有类型", tags = {
        "获取角色", "所有角色"})
    @ApiResponse(code = 200, message = "返回正常")
    public List<G2AdminRoleAccess> getRoles(){
        
        return roleAccessService.listAllRole();
    }
    
    @RequestMapping(value = "listByPage", method = RequestMethod.GET)
    @ResponseBody
    public List<G2AdminRoleAccess> getRolesByPage(
            @ApiParam(value = "页码") @RequestParam(value = "page", defaultValue = "1") int page,
            @RequestParam(value = "size", defaultValue = "10") int size){
        
        return roleAccessService.listRole(page, size);
    }

至此上面介绍了常见的标签，大部分情况下够用了，以下贴出全部代码。

controller类代码：

@Controller
    @RequestMapping("/yx-user")
    @Api(tags = {
        "用户模块"})
    public class YxUserController {
        
        @Autowired
        private RoleAccess roleAccessService;
    
        @RequestMapping(value = "listAll", method = RequestMethod.GET)
        @ResponseBody
        @ApiImplicitParams({
        
            @ApiImplicitParam()
        })
        @ApiOperation(value = "获取角色所有类型", tags = {
        "获取角色", "所有角色"})
        @ApiResponse(code = 200, message = "返回正常")
        public List<G2AdminRoleAccess> getRoles(){
        
            return roleAccessService.listAllRole();
        }
    
        @RequestMapping(value = "listByPage", method = RequestMethod.GET)
        @ResponseBody
        public List<G2AdminRoleAccess> getRolesByPage(
                @ApiParam(value = "页码") @RequestParam(value = "page", defaultValue = "1") int page,
                @RequestParam(value = "size", defaultValue = "10") int size){
        
            return roleAccessService.listRole(page, size);
        }
    
        @RequestMapping(value = "addRole", method = RequestMethod.POST)
        @ApiImplicitParam(name = "role", value = "权限信息", dataTypeClass = G2AdminRoleAccess.class, required = true)
        @ApiResponses({
        
            @ApiResponse(code = 200, message = "返回正常"),
            @ApiResponse(code = 404, message = "请求路径不存在"),
        })
        public int addRole(@RequestBody G2AdminRoleAccess role){
        
            return roleAccessService.addRole(role);
        }
    }

model类代码：

总体来说swagger2代码还是容易理解，如果遇到问题，可以下载源代码看下其中的英文描述。此篇文章是针对单个应用集成的，对于多应用微服务，接口相对较繁杂，在架构中我们需要提前就要划分好模块，使得后面开发起来更便捷。在下一篇中我们来研究一下如何实现微服务下整合swagger2。

[285cc8a3d73a4420ac24573928045674.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/25/8598228297ae4339af718a60d24f5dca.jpeg
[2d0596be547644319591fa05609735b6.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/25/e0ac54f99f194e97afd9e3c9c201fefd.jpeg