swagger2配置及注释详解

原创 已于 2022-10-19 19:21:36 修改 · 2.3k 阅读 · 9 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#java #spring #swagger

于 2022-10-19 19:18:59 首次发布
本文详细介绍Swagger2配置，包括接口分组、路径选择、注释标签的使用，帮助开发者快速创建和管理API文档。涵盖了@Api、@ApiParam等常见注解的详细说明和示例。

前面我们记录了如何整合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.youkuaiyun.com/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如下：

在这里插入图片描述

常见注释说明及用法

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

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

标签使用位置描述
@ApiController请求类说明
@ApiIgnoreController隐藏说明，无需参数
@ApiParamMethod方法参数说明
@ApiImplicitParamMethod方法单个参数说明
@ApiImplicitParamsMethod方法参数的说明
@ApiResponseMethod单个返回状态码说明
@ApiResponsesMethod方法返回状态码说明
@ApiModelModel实体类说明
@ApiModelPropertyModel属性实体类属性说明
@JsonIgnoreModel属性隐藏说明
@ApiOperationMethod方法说明
  • @api标签说明：
标签说明
tags标题描述，支持多个标题
produces生产者，输出什么内容，如"application/json, application/xml"
consumes消费者，输入什么内容，如上
protocols请求协议规则
authorizations安全设置
hidden是否隐藏
  • @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);
}

具体参数

标签说明
name名称
value字段描述
defaultValue默认值
allowableValues可允许值
required是否必须
allowMultiple是否为集合
dataType参数数据类型，int、float、String等等
dataTypeClass参数指定类类型
paramType参数类型，包括path、query、body、header、form
example举例
Example实体类举例
allowEmptyValue是否可为空
readOnly是否只读
  • @ApiImplicitParam标签说明：

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

@RequestMapping(value = "addRole", method = RequestMethod.POST)
@ApiImplicitParam(name = "role", value = "权限信息", dataTypeClass = G2AdminRoleAccess.class, required = true)
public int addRole(@RequestBody G2AdminRoleAccess role){
    return roleAccessService.addRole(role);
}
  • @ApiImplicitParams标签说明：

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

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

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

标题说明
code返回码
message返回消息
response抛出异常的类
responseHeaders定义响应头

参考如下：

@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标签说明：
标签说明
value标题
description描述
parent所属父类
@ApiModel(value = "用户角色", description = "用户角色信息")
public class G2AdminRoleAccess implements Serializable {
}
  • @ApiModelProperty模型属性标签：
标签说明
value标题
allowableValues可允许值
dataType数据类型
required是否必须
position排序位置
readOnly是否只读
allowEmptyValue是否为空

举例：

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

    /**
     * 角色ID
     *
     * @mbg.generated
     */
    @ApiModelProperty(value = "角色ID")
    private Integer roleId;
}
  • @JsonIgnore标题说明：

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

  • @ApiOperation标签说明：

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

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

代码如下：

@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类代码：

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

    /**
     * 角色ID
     *
     * @mbg.generated
     */
    @ApiModelProperty(value = "角色ID")
    private Integer roleId;
}

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

Swagger的原理及应用详解（四）
凛鼕将至的博客
07-04 2009
Swagger（OpenAPI Specification）是一个功能强大的框架和规范，它通过自动化生成文档、提供详细的API描述以及支持调用和可视化等功能，极大地简化了API的设计、构建、使用和理解过程。无论是在企业内部还是跨企业的API合作中，Swagger都发挥着重要的作用。 本文将跟随《Swagger的原理及应用详解（三）》的进度，继续介绍Swagger。希望通过本系列文章的学习，您将能够更好地理解Swagger的内部工作原理，掌握Swagger的使用技巧，以及通过合理的设计完成最
ASP.NET Core Web API 中的 Swagger 配置详解
m0_74337424的博客
05-29 619
在 ASP.NET Core Web API 项目中，Swagger 是一个非常有用的工具，它可以帮助开发人员生成和展示 API 文档。然而，有时我们会遇到一些棘手的问题，例如如何正确地将授权头信息（如 “Authorization”）包含在 Swagger 的文件中。本文将详细探讨这一问题，并提供解决方案。
Swagger2配置
m0_56525833的博客
04-05 582
Swagger 是一个规范和完整的框架，用于生成、描述、功能调用测试和可视化 RESTful 风格的在线的接口文档工具。Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具。Swagger 提供了一套通过代码和注解自动生成可视化的 RESTful 风格的API文档，符合 RESTful API设计的行业标准。
Swagger2的配置
lmxx9939的博客
06-06 2600
使用Swagger 2是为了解决前后端接口之间的交互问题提示：以下是本篇文章正文内容，下面案例可供参考后面扩展的方法是为了实现这两个方法我们需要了解这两个方法的作用：securityContexts 和 securitySchemes 是用于配置 Swagger 文档中的安全认证信息的两个关键部分。securityContexts：安全上下文securityContexts 方法用于配置需要进行安全认证的路径和相应的安全引用。
Swagger2Config配置文件的源代码展示
最新发布
ai12345678900008的博客
10-06 400
该Swagger2配置类实现了前后端分离项目的API文档自动生成功能。通过两个@Bean方法分别创建web和admin接口分组：webApiConfig()配置前台接口(/api/路径)，adminApiConfig()配置后台接口。关键配置包括：1)使用ParameterBuilder添加全局header参数(如userId)；2)通过Docket对象设置扫描路径(basePackage)、接口过滤规则(regex)；3)通过ApiInfoBuilder定制文档标题、版本、联系人等元信息。启动后访问/sw
springboot 整合swagger2 ，搭建 RESTful API 在线文档
殇莫忆的博客
01-16 566
1、pom 文件引入jar包 &lt;dependency&gt; &lt;groupId&gt;io.springfox&lt;/groupId&gt; &lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt; &lt;version&gt;2.7.0...
Swagger——【SpringBoot集成Swagger、配置Swagger、配置扫描接口、配置API分组】
2401_84003733的博客
04-18 1451
直接运行，在线测试API支持多种语言 （如：Java，PHP等）
Swagger的原理及应用详解（十）
凛鼕将至的博客
07-07 936
Swagger（OpenAPI Specification）是一个功能强大的框架和规范，它通过自动化生成文档、提供详细的API描述以及支持调用和可视化等功能，极大地简化了API的设计、构建、使用和理解过程。无论是在企业内部还是跨企业的API合作中，Swagger都发挥着重要的作用。 本文将跟随《Swagger的原理及应用详解（九）》的进度，继续介绍Swagger。希望通过本系列文章的学习，您将能够更好地理解Swagger的内部工作原理，掌握Swagger的使用技巧，以及通过合理的设计完成
使用Swagger进行API文档管理详解
fudaihb的博客
07-12 1051
在现代软件开发中，API（应用程序接口）是前后端通信的重要桥梁。随着项目的规模和复杂度增加，管理API文档变得愈发重要。Swagger是一个开源工具，可以帮助开发者自动生成、维护和分享API文档。本文将详细介绍Swagger的使用方法，帮助你在项目中更好地管理API文档。
Spring Boot整合Swagger2 Swagger2配置
九离的博客
06-05 1288
Swagger是一款流行的RESTful API文档生成工具，它支持多种编程语言和多种框架，包括但不限于Java、Python、Node.js、Go等，Spring Boot也提供了对Swagger的支持。Swagger可以根据注解生成API文档，支持在线测试API接口、生成客户端代码等多种功能。
Swagger2配置（2024.9.13）
wy990880的博客
09-13 950
然后在application.yml文件上配置。配置完成 记得这是swagger2。我的springboot版本是。最后配置 swagger文件。然后是controller层。我的端口号是：8081。
Swagger系列——Swagger2配置
weixin_42526326的博客
08-28 3975
Swagger-Swagger2配置依赖引入详细配置swagger资源访问路径加入白名单访问路径：小技巧： 相关内容 地址 Swagger官方文档 https://swagger.io/docs/specification/2-0/basic-structure/ Swagger2常用注解 https://blog.youkuaiyun.com/weixin_42526326/article/details/119824857 依赖引入 <!-- swagger
Swagger2 配置
m0_46294211的博客
09-09 368
swagger2 配置
评论 1
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值