Swagger 笔记
Swagger 简介#
Open API#
Open API规范(OpenAPl Specification),以前叫做Swagger规范,是REST API的API描述格式。
Open API文件允许描述整个API,包括:
- 每个访问地址的类型,POST 或 GET。
- 每个操作的参数。包括输入输出参数。
- 认证方法。
- 连接信息,声明,使用团队和其他信息。
Open API规范可以使用YAML 或JSON格式进行编写。这样更利于我们和机器进行阅读。
Swagger#
Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。
Swagger工具包括的组件:
- Swagger Editor:基于浏览器编辑器,可以在里面编写ОpenAPI规范。类似 Markdown具有实时预览描述文件的功能。
- Swagger Ul:将Open API规范呈现为交互式API文档。用可视化U展示描述文件。
- Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成 html格式和cwiki形式的接口文档,同时也可以生成多种言语的客户端和服务端代码。
- Swagger Inspector:和Swagger Ul有点类似,但是可以返回更多信息,也会保存请求的实际参数数据。
Springfox#
使用Swagger时如果碰见版本更新或迭代时,只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json)也是一定的工作负担,久而久之就直接修改代码,而不去修改描述文件了,这样基于描述文件生成接口文档也失去了意义。
Marty Pitt编写了一个基于Spring的组件 swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。
Spring-fox是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码而不需要跟随修改描述文件。
Spring-fox利用自身AOP特性,把Swagger集成进来,底层还是Swagger。但是使用起来确方便很多。
所以在实际开发中,都是直接使用spring-fox。
Swagger 配置#
pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
1、配置基本信息#
@Configuration
public class SwaggerConfig {
@Bean
// 创建Docket的bean方法
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo()) // 设置具体的摘要信息
.select()
.build();
}
// 创建存储了摘要信息的APIInfo信息
public ApiInfo swaggerDemoApiInfo() {
return new ApiInfoBuilder()
.contact(new Contact("百度","http://www.baidu.com", "xx@163.com"))
.title("这里是swagger标题")
.description("这里是swagger的描述信息")
.version("1.0.0") // 文档的版本信息
.build();
}
}
2、设置扫描的包#
apis()
:设置扫描的包路径
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.baizhi.user.controller"))
.build();
}
3、自定义注解设置不需要生成接口文档的方法#
3.1 自定义注解#
建立一个包annotation
,在下面建一个annotation!类
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger{
}
3.2 添加规则#
apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
可以设置生成规则
public static <T> Predicate<T> not(Predicate<T> predicate)
:表示不允许的条件withMethodAnnotation
:表示此注解是方法级别注解。
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.apis(not(withMethodAnnotation(NotIncludeSwagger.class))) //
.build();
}
3.3 添加 NotIncludeSwagger 注解#
在不需要生成接口文档的犯法上面添加 @NotIncludeSwagger
注解后,该方法将不会被Swagger进行生成在接口文档中。
@NotIncludeSwagger
@RequestMapping("/userInfo")
public ... {}
4、设置范围(用的不多)#
.paths()
设置满足什么规则的url被生成接口文档,可以用正则表达式进行匹配。
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.paths(allowPaths())
.build();
}
public Predicate<String> allowPaths() {
return or(
regex("/demo/.*")
);
}
其中
.
:在正则表达式中表示任意字符*
:表示可以出现n次
Swagger 常用注解#
1、@Api#
@Api 是类上注解。控制整个类生成接口信息的内容。
tags
:类的名称。可以有多个值,多个值表示多个副本description
:描述,已过时。
@RestController
@RequestMapping("/people")
@Api(tags = {"mydemo"}, description = "描述")
public class DemoController {}
2、@ApiOperation#
@ApiOperation
:写在方法上,对方法进行总体描述
value
:接口描述notes
:提示信息
@ApiOperation(value = "接口描述", notes = "接口提示信息")

3、@ApiParam#
@ApiParam
:写在方法参数前面。用于对参数进行描述或说明是否为必填项等说明。
name
:参数名称(不建议改)value
:参数描述required
:是否是必须
public People getPeople(Integer id, @ApiParam(value="姓名", required=true) String name, String address)
4、@ApiModel#
@ApiModel
:是类上注解,主要应用Model,也就是说这个注解一般都是写在实体类上。
value
:名称description
:描述
@ApiModel(value = "人类", description = "描述")
public class People {}
5、@ApiModelProperty#
@ApiModelProperty
:可以用在方法或属性上。用于当对象作为参数是定义这个字段的内容。
value
:名称name
:重写属性名required
:是否是必须的example
:实例内容hidden
:是否隐藏
@ApiModelProperty(value = "姓名", name = "name", required = true, example = "zhang'san")
private String name;
6、@ApiIgnore#
@Apilgnore用于方法或类或参数上,表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解,@NotIncludeSwagger是我们自定义的注解。
7、@ApiImplicitParam#
@ApilmplicitParam
用在方法上,表示单独的请求参数,总体功能和@ApiParam类似。
name
:属性名value
:描述required
:是否是必须的paramType
:属性类型dataType
:数据类型
@PostMapping("/getPeople")
@ApiImplicitParam(name = "address", value = "地址", required = true, paramType = "query", dataType = "string")
public People getPeople(Integer id, @ApiParam(value = "姓名", required = true)String name, String address)
作者:stdxiaozhang
出处:https://www.cnblogs.com/stdxiaozhang/p/17069992.html
版权:本作品采用「署名-非商业性使用-相同方式共享 4.0 国际」许可协议进行许可。
吼吼,如果对你有帮助的话,可以点个赞呀!
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· 清华大学推出第四讲使用 DeepSeek + DeepResearch 让科研像聊天一样简单!
· 实操Deepseek接入个人知识库
· CSnakes vs Python.NET:高效嵌入与灵活互通的跨语言方案对比
· Plotly.NET 一个为 .NET 打造的强大开源交互式图表库