作为一个经常要提供给API文档给内部和第三方的阅读的“苦程”,我一直在寻找一个完美的Spring MVC文档解决方案。过去,我一直使用的是springfox-swagger2
依赖,使用swagger2
注解,对代码进行注释,生成swagger文档。 不过,现在是2020年了,Swagger2早已过时啦,springfox-swagger2
也已停止维护。这里,我向大家分享一个自己的文档解决方案。使用OAS3 + ReDoc ,轻轻松松就能为已有的Spring Boot应用生成精美的API文档,并且可以加入自定义的Markdown文档。
先来看看最终生成的文档效果吧:
为了方便大家使用,我将解决方案封装为了spring-boot-starter
,只需要引入现有的Spring Boot MVC应用中,无需任何配置,就可以立刻为应用加入精美的ReDoc和Swagger-UI文档。
项目已经开源到了GitHub: https://github.com/hehongyu1995/oas3-redoc-spring-boot-starter
如果你喜欢这个项目,欢迎给它加星~使用中遇到的各种问题,或者建议。欢迎给我提issue,或者直接在文章下方留言。
下面是该starter的使用说明:
引入Starter
引入依赖前,请将以下私服加入项目的仓库配置中:
https://hehongyu1995.github.io/maven-repo/maven-releases/
- Maven
<dependency>
<groupId>cn.hongyu</groupId>
<artifactId>oas3-redoc-spring-boot-starter</artifactId>
<version>0.0.1</version>
</dependency>
- Gradle
dependencies{
implementation("cn.hongyu:oas3-redoc-spring-boot-starter:0.0.1")
}
添加OAS3文档注解
OAS3可用的全部注解,请参考官方文档:Quick Annotation Overview
为Controller添加文档注解
使用OAS3注解标记Controller的方法和参数,以下以Kotlin代码为例:
@RestController
@RequestMapping("/cat")
@Tag(name = "猫咪登记", description = "登记各种主子")
@SecurityRequirement(name = SecuritySchemeConstants.BearerAuthentication)
class CatController {
private val cats = mutableListOf<Cat>()
@GetMapping
@Operation(summary = "列出所有猫咪", description = "列出所有已登记的猫咪")
fun listDogs(): List<Cat> = cats
@PostMapping
@Operation(summary = "添加猫咪",description = "登记一只猫咪")
@ApiResponse(description = "是否登记成功")
fun addDog(@RequestBody cat: Cat): Boolean{
cats.add(cat)
return true
}
}
在Java中使用也是类似的。
对请求和返回类添加文档注解
对于请求类和返回类,使用@Schema
注解进行标记:
@Schema(name = "猫")
data class Cat(
@field:NotBlank
@field:Schema(description = "名字")
val name: String,
@field:Min(0)
@field:Schema(description = "年龄")
val age: Int
)
对OAS3生成的API文档进行定制
新建一个配置类OAS3Config.java
:
@Configuration
class OAS3Config {
@Bean
fun customOpenApiCustomizer(): OpenApiCustomiser{
return OpenApiCustomiser {
// 添加Servers配置
configureApiServers(it, "oas-document/servers.json")
// 添加文档介绍
configureApiDescription(it, "oas-document/api-description.md")
// 对API进行分组
configureTagGroups(it, listOf(
TagGroup("宠物登记", listOf("猫咪登记","犬只登记"))
))
}
}
}
这里,我们通过实现OpenApiCustomiser
类,对OAS3生成的OpenAPI
对象进行额外的配置。
本Starter包中的OASDocumentUtil
中提供了以下工具方法,方便使用者对OpenAPI
进行修改:
configureApiServers|配置文档展示的服务器列表 configureTagGroups|配置文档的API分组,利用了ReDoc
支持的x-tagGroups
扩展 configureApiDescription|配置文档的描述,支持读取resources
目录下的Markdown文件,并支持插入其他文档
对于Java代码,使用也是类似的,使用OASDocumentUtilKt.configureApiServers()
等静态方法即可。
如果需要修改文档的Logo和标题等信息,在OAS3Config
类上添加@OpenAPIDefinition
注解即可:
@OpenAPIDefinition(
info = Info(
title = "示例API - 文档",
version = "1.0.0",
extensions = [
Extension(name = "logo", properties = [
ExtensionProperty(
name = "url", value = "https://s1.ax1x.com/2020/08/18/dMBXqI.jpg"
)
])
]
)
)
使用Mardown自定义文档的描述
OAS3的文档定义中,提供了description
字段,可供我们在里面填写API和应用的介绍、API调用说明等。如果利用注解的话,我们将只能写入一些简单的介绍。因此,我在Starter中加入了一个可以在最终文档中插入自定义Markdown的解决方案:
在项目的src/main/resources
目录下,放置自己的markdown,以example的目录结构为例:
其中,api-description
为主文件,内容为:
@oas-document/introduction.md@
@oas-document/FAQ.md@
对OpenAPI进行配置:
@Configuration
class OAS3Config {
@Bean
fun customOpenApiCustomizer(): OpenApiCustomiser{
return OpenApiCustomiser {
// 添加文档介绍,oas-document/api-description.md为主文件
configureApiDescription(it, "oas-document/api-description.md")
}
}
}
运行时,api-description
的内容将作为API文档的description字段。并且,如果其中有以@{filePath}@
格式定义的占位符,将被替换为src/main/resources
下对应文件的内容。
启动Spring Boot应用
启动应用,不出意外的话,控制台应该可以打印出以下日志:
---
Swagger UI is enabled at endpoint `/swagger-ui.html`
ReDoc is enabled at endpoint `/doc`
ReDoc title: $title
---
看到这个日志,就说明Starter已经自动配置好了Swagger-UI
和ReDoc
文档。
打开浏览器,进入http://localhost:8080/doc
或 http://localhost:8080/swagger-ui.html
即可看到效果:
- ReDoc文档:
- Swagger-UI文档: