Spring Boot（9）之 Swagger 接口文档生成器
2024-04-30 00:44:59
1、添加依赖
spring4all工具源码
<dependency><groupId>com.spring4all</groupId><artifactId>swagger-spring-boot-starter</artifactId><version>1.9.1.RELEASE</version></dependency>
2、入口添加注释
import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@EnableSwagger2Doc // 启动文档
@SpringBootApplication
public class OsFastStableApplication {public static void main(String[] args) {SpringApplication.run(OsFastStableApplication.class, args);}}
3、常用注解
3.1、@Api()：类
用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源
| 参数 | 说明 | 备注 |
|---|---|---|
tags
|
说明该类的作用（标签），参数是个数组，可以填多个 | |
value
|
该参数没什么意义，在UI界面上不显示，所以不用配置 | |
description
|
类的描述 |
3.2、@ApiOperation()：方法
用于方法，表示一个http请求访问该方法的操作
| 参数 | 说明 | 备注 |
|---|---|---|
value
|
方法的用途和作用 | |
notes
|
方法的注意事项和备注 | |
tags
|
说明该方法的作用，参数是个数组，可以填多个 | 格式：tags={“作用1”,“作用2”} |
注意：在这里建议不使用 tags 这个参数，会使界面看上去有点乱，前两个常用
3.3、@ApiModel()：实体类
用于响应实体类上，用于说明实体作用
| 参数 | 说明 | 备注 |
|---|---|---|
description
|
描述实体的作用 |
3.4、@ApiModelProperty()：实体类属性
用在属性上，描述实体类的属性
| 参数 | 说明 | 备注 |
|---|---|---|
name
|
参数的变量名 | name=“name” |
value
|
描述参数的意义 | value=“用户名” |
required
|
参数是否必选 | required=true |
3.5、@ApiImplicitParams()：请求方法
用在请求的方法上，包含多@ApiImplicitParam
@ApiImplicitParams(value = {@ApiImplicitParam( ... ),@ApiImplicitParam( ... )
})
3.6、@ApiImplicitParam()：请求方法
用于方法，表示单独的请求参数
| 参数 | 说明 | 备注 |
|---|---|---|
name
|
参数的变量名 | |
value
|
描述参数的意义 | |
dataType
|
数据类型 | |
paramType
|
表示参数放在哪里 |
· header 请求参数的获取：@RequestHeader · query 请求参数的获取：@RequestParam · path（用于restful接口） 请求参数的获取：@PathVariable · body（不常用） · form（不常用） |
defaultValue
|
参数的默认值 | |
required
|
表示参数是否必须传 | required=true |
3.7、@ApiParam()：方法参数
用于方法，参数，字段说明 表示对参数的要求和说明
- 注意：@ApiParam 与 @ApiImplicitParam 作用相同，但是 @ApiImplicitParam 的适用范围更广
| 参数 | 说明 | 备注 |
|---|---|---|
name
|
参数的变量名 | name=“name” |
value
|
描述参数的意义 | value=“用户名” |
defaultValue
|
参数默认值 | |
required
|
参数是否必选 | 默认为false |
@ApiOperation("用户列表")@GetMapping("/users")public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,@ApiParam("每页多少条") @RequestParam int pageSize) {List<User> result = new ArrayList<>();result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));return result;}
3.8、@ApiResponses()：请求方法
用于请求的方法上，根据响应码表示不同响应
- 一个@ApiResponses包含多个@ApiResponse
@ApiResponses(value = {@ApiResponse(code = 200, message = "Success", response = Order.class),@ApiResponse(code = 405, message = "Error", response = Order.class)
})
3.9、@ApiResponse()：请求方法
用在请求的方法上，表示不同的响应
| 参数 | 说明 | 备注 |
|---|---|---|
code
|
表示响应码(int型) | 可自定义 |
message
|
状态码对应的响应信息 | |
response
|
返回响应 | Class类型 |
...
|
其他参数不常用 | 可以自行查看源码 |
3.10、@ApiIgnore()：类、方法
用于类或者方法上，不被显示在页面上
3.11、@Profile({“dev”, “test”})：配置类
用于配置类上，表示只对开发和测试环境有用
4、配置详情
4.1、其他
| 命令 | 说明 | 案例 |
|---|---|---|
| spring.application.name | spring 应用程序名称 | swagger-demo |
| logging.level.org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping | trace |
4.2、Swagger Enable/Disable
| 命令 | 说明 | 案例 |
|---|---|---|
| springfox.documentation.enabled | TRUE |
4.3、Swagger Switch
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.enabled | 是否启用swagger，默认：true |
4.4、ApiInfo
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.title | 标题 | spring-boot-starter-swagger |
| swagger.description | 描述 | Starter for swagger 2.x |
| swagger.version | 版本 | 1.1.0.RELEASE |
| swagger.license | 许可证 | Apache License, Version 2.0 |
| swagger.licenseUrl | 许可证URL | https://www.apache.org/licenses/LICENSE-2.0.html |
| swagger.termsOfServiceUrl | 服务条款URL | https://github.com/dyc87112/spring-boot-starter-swagger |
| swagger.contact.name | 维护人 | didi |
| swagger.contact.url | 维护人URL | http://blog.didispace.com |
| swagger.contact.email | 维护人email | dyc87112@qq.com |
| swagger.host | 文档的host信息，默认：空 | localhost:8081 |
| … | … | … |
| swagger.base-package | swagger扫描的基础包，默认：全扫描 | com.didispace |
| swagger.base-path |
需要处理的基础URL规则，默认：/**
|
/**
|
| swagger.exclude-path | 需要排除的URL规则，默认：空 |
/error, /ops/**
|
4.5、忽略的参数配置
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.ignored-parameter-types[0] | com.didispace.demo.User | |
| swagger.ignored-parameter-types[1] | com.didispace.demo.Product |
4.6、全局请求参数
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.global-operation-parameters[0].name | 参数名 | access_token |
| swagger.global-operation-parameters[0].description | 描述信息 | user access token |
| swagger.global-operation-parameters[0].modelRef | 指定参数类型 | string |
| swagger.global-operation-parameters[0].parameterType | 指定参数存放位置,可选header,query,path,body.form | header |
| swagger.global-operation-parameters[0].required | 指定参数是否必传，true,false | TRUE |
5、取消使用默认预定义的响应消息,并使用自定义响应消息
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.apply-default-response-messages | FALSE | |
| swagger.global-response-message.get[0].code | 401 | |
| swagger.global-response-message.get[0].message | 401get | |
| swagger.global-response-message.get[1].code | 500 | |
| swagger.global-response-message.get[1].message | 500get | |
| swagger.global-response-message.get[1].modelRef | ERROR | |
| swagger.global-response-message.post[0].code | 500 | |
| swagger.global-response-message.post[0].message | 500post | |
| swagger.global-response-message.post[0].modelRef | ERROR |
5.1、UI功能配置
| 命令 | 说明 | 案例 |
|---|---|---|
| swagger.ui-config.json-editor | json编辑器 | FALSE |
| swagger.ui-config.show-request-headers | 显示请求头 | TRUE |
| swagger.ui-config.request-timeout | 页面调试请求的超时时间 | 5000 |
| swagger.ui-config.submit-methods | 调试按钮的控制(try it out)，该参数值为提供调试按钮的HTTP请求类型，多个用,分割。 | get,delete |
5.2、分组配置
| 命令 | 说明 | 案例 |
|---|---|---|
swagger.docket.<name>.title
|
标题 | |
swagger.docket.<name>.description
|
描述 | |
swagger.docket.<name>.version
|
版本 | |
swagger.docket.<name>.license
|
许可证 | |
swagger.docket.<name>.licenseUrl
|
许可证URL | |
swagger.docket.<name>.termsOfServiceUrl
|
服务条款URL | |
swagger.docket.<name>.contact.name
|
维护人 | |
swagger.docket.<name>.contact.url
|
维护人URL | |
swagger.docket.<name>.contact.email
|
维护人email | |
swagger.docket.<name>.base-package
|
swagger扫描的基础包，默认：全扫描 | |
swagger.docket.<name>.base-path
|
需要处理的基础URL规则，默认：/**
|
|
swagger.docket.<name>.exclude-path
|
需要排除的URL规则，默认：空 | |
swagger.docket.<name>.name
|
参数名 | |
swagger.docket.<name>.modelRef
|
指定参数类型 | |
swagger.docket.<name>.parameterType
|
指定参数存放位置,可选header,query,path,body.form | |
swagger.docket.<name>.required
|
TRUE | |
swagger.docket.<name>.globalOperationParameters[0].name
|
参数名 | |
swagger.docket.<name>.globalOperationParameters[0].description
|
描述信息 | |
swagger.docket.<name>.globalOperationParameters[0].modelRef
|
指定参数存放位置,可选header,query,path,body.form | |
swagger.docket.<name>.globalOperationParameters[0].parameterType
|
指定参数是否必传，true,false |
6、Swagger UI 地址
http://localhost:8081/swagger-ui.html#/
Spring Boot（9）之 Swagger 接口文档生成器相关推荐
- springboot 接口文档 请求 enum_Spring Boot集成SpringFox 3：生成Swagger接口文档
SpringFox介绍 SpringFox是一个开源的API Doc的框架, 它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现.官方定义为:Aut ...
- sentinel 官方文档_SpringCloud网关聚合Swagger接口文档实践
目前大多数项目都是以微服务架构设计,以前后端分离技术解耦前端开发工程师和后端开发工程师的工作量,这样一来前后端的对接将是一项重要的沟通工作量,如果后端没有一个合适的API文档,那么这样的前后端对接将是 ...
- SpringBoot集成knife4j实现Swagger接口文档
前言:如果你是后台开发,提供restful接口给前端,建议你使用Swagger3提供restful的接口文档自动生成和在线接口调试.knife4j是对Swagger进一步封装,其优化了API文档的UI ...
- swagger接口文档使用
swagger接口文档 一,swagger简介 前后端分离 swagger 诞生 二,springboot集成swagger 依赖 编写helloworld接口 配置swagger ==> co ...
- swagger接口文档分组
swagger接口文档分组 解析问题 因项目中的接口越来越多,使用swagger调试接口的时候,因接口太杂太乱,不太容易找到想要调试的接口,所以研究了一下swagger分组的方法 但是分组是需要配置多 ...
- 整合Swagger接口文档
Swagger接口文档:自动生成接口文档 1.添加依赖: <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagg ...
- 自动生成python接口文档_Django自动生成Swagger接口文档
Django自动生成Swagger接口文档 1. 前言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次 ...
- swagger接口文档出现的空文档问题
记一次使用swagger接口文档出现的空文档问题 问题描述: 上面显示的一些空文档 下面的才是真正的正确文档: 最终尝试发现问题: 原因:**@Api(value = "ExamPaperC ...
- python实现处理swagger接口文档，转换为yaml格式的自动化用例
前言 之前有很多小伙伴反馈,希望我出一期 将swagger文档转换为 yaml格式的自动化用例,那么本期福利来咯~~这一篇文档,将会带领你们实现 如何通过 swagger文档转换为 yaml格式的用例 ...
最新文章
- textContent与innerText的不同（转发）
- python爬去百度文库_利用Python语言轻松爬取数据[精品文档]
- 通俗讲解傅里叶变换fft
- 同一端口是否可以绑定到多个IP上（关于Socket编程中地址与端口绑定那些事）
- 中职生转段计算机应用基础,吉林省2017年高等职业教育对口升学、中职—本科衔接试点转段考试安排通知...
- linux svn 版本安装,有人有linux版本的svn安装包吗
- 在移动设备中创建ArcGIS API for JavaScript地图应用程序
- android 无网络处理布局,Android网络开发
- 以太坊2.0怎么挖矿_以太坊2.0即将上线 现在正是挖矿红利期 普通人如何参与挖矿？...
- Guava 相关文章
- 搭建appium的android环境
- C#项目实例中读取并修改App.config文件
- 全网最新抖音视频去水印解析PHP网页源码
- luckysheet实现打印功能
- Python利用pptx模块三步将图片插入特定PPT模板
- Markdown 内如何使用表情符号
- h5课件制作_PPT轻松转化H5，让“课件”动起来！
- （九）苏世民：我的经验和教训：苏世民成功投资的十五条法则
- 免费开源的云尚发卡V1.5.7
- Vscode好用的快捷键：批量文字修改快捷键选中相同内容快捷键