不用Swagger,那我用啥?
@[toc]
上周松哥写了一篇文章和小伙伴们分享 Swagger3 在 Spring Boot 中的用法,评论中有不少小伙伴推荐 Spring Doc,松哥趁着休息时间抽空看了下,这个东西确实不错,不存在和 Spring Boot 之间的兼容问题,于是就撸了这篇文章和小伙伴们分享。一起来看看这个好玩的文档生成工具吧!
1. OpenApi
在正式学习 Spring Doc 之前,先给大家介绍一下 OpenAPI。
OpenApi 是一个业界的 API 文档标准,是一个规范,这个规范目前有两大实现,分别是:
- SpringFox
- SpringDoc
其中 SpringFox 其实也就是我们之前所说的 Swagger,SpringDoc 则是我们今天要说的内容。
OpenApi 就像 JDBC 一样,制定了各种各样的规范,而 Swagger 和 SpringDoc 则类似于各种各样的数据库驱动,是具体的实现。
所以可能很多小伙伴也发现了,Swagger 和 Spring Doc 有一些相似的地方,这就是因为他们都遵守了相同的规范。
不过呢,Swagger 更新有点慢吞吞的,为了能够和新版的 Spring Boot 整合,还是 SpringDoc 更值得体验一把。
SpringDoc 支持:
- OpenAPI 3
- Spring-boot,全版本都支持。
- JSR-303 中提供的一些注解,例如
@NotNull
、@Min
、@Max
以及@Size
等。 - Swagger-ui:SpringDoc 提供的接口 JSON 也可以通过 Swagger-ui 展示出来。
- OAuth 2
- ...
2. 引入 SpringDoc
小伙伴们知道,这种生成接口文档的工具,一般来说都是两方面的功能:
- 生成接口文档 JSON。
- 渲染接口文档 JSON。
所以,当我们使用 SpringDoc 的时候,如果只是想要生成接口文档 JSON,那么只需要添加如下依赖即可:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId>
<version>1.6.9</version>
</dependency>
此时,就会针对项目中的接口自动生成接口的 JSON 文档,类似下面这样:
这样的 JSON 信息开发者可以自行将之绘制出来,也可以使用网上一些现成的工具例如 Knife4j 之类的。当然你要是不想费事,也可以使用 SwaggerUI 将之绘制出来,如果想使用网页,那么就不要使用上面的依赖,用下面这个依赖,不仅可以生成 JSON 接口,还可以生成渲染后的网页:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
网页效果如下图:
这个网页看着眼熟,其实就是 Swagger UI。
这个网页上有一个输入框,输入的内容是 /v3/api-docs
,这个地址就是这个网页想要渲染的 JSON 的地址,如果开发者修改了生成的 JSON API 文档的地址,那么就需要手动在这个输入框中输入一下 JSON API 文档的地址。
默认的 JSON API 文档地址是:
- /v3/api-docs
默认的网页 UI 地址是:
- /swagger-ui/index.html
如果需要配置,则可以在 Spring Boot 的 application.properties 中直接进行配置:
springdoc.swagger-ui.path=/javaboy-ui
springdoc.api-docs.path=/javaboy-api
不过这两个配置并不是真的修改了访问路径,这两个相当于给访问路径取了一个别名,访问这两个时会自动重定向到对应的路径上。
3. 结合 Spring Security
如果我们的项目中使用了 Spring Security,那么部分接口的参数可能会比较特殊,例如下面这个接口:
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(@AuthenticationPrincipal User user) {
System.out.println("user = " + user);
return "hello";
}
}
这个接口的参数加上了一个 @AuthenticationPrincipal
注解表示当前登录成功的用户对象,这个参数在实际使用中,并不需要前端传递,服务端会自动注入该参数。
但是!如果使用了 SpringDoc,通过网页去调用这个接口的时候,这个参数就必须要要传递,对于这种问题,我们可以引入如下依赖自动帮我们解决:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-security</artifactId>
<version>1.6.9</version>
</dependency>
这个依赖会自动帮我们忽略掉接口中带有 @AuthenticationPrincipal 注解的参数,这样我们在通过 swagger-ui 去进行接口测试的时候就不需要传递这个参数了。
4. 结合 Spring Data Rest
Spring Boot 中提供了 Spring Data Rest,结合 Jpa 可以非常方便的构建出 Restful 应用。但是这种 Restful 应用不需要开发者自己写接口,那么怎么生成接口文档呢(连接口在哪里都不知道)?针对于此,SpringDoc 也提供了相关的支持,我们一起来看下。
4.1 Spring Data Rest
创建工程
首先创建一个 Spring Boot 工程,引入 Web
、 Jpa
、 MySQL
、 Rest Repositories
依赖:
配置数据库
主要配置两个,一个是数据库,另一个是 Jpa:
spring.datasource.username=root
spring.datasource.password=1234
spring.datasource.url=jdbc:mysql:///test02?serverTimezone=Asia/Shanghai
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.database=mysql
spring.jpa.database-platform=mysql
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect
这里的配置,和 Jpa 中的基本一致。
前面三行配置了数据库的基本信息,包括数据库连接池、数据库用户名、数据库密码、数据库连接地址以及数据库驱动名称。
接下来的五行配置了 JPA 的基本信息,分别表示生成 SQL 的方言、打印出生成的 SQL 、每次启动项目时根据实际情况选择是否更新表、数据库平台是 MySQL。
这两段配置是关于 MySQL + JPA 的配置,没用过 JPA 的小伙伴可以参考松哥之前的 JPA 文章: http://www.javaboy.org/2019/0407/springboot-jpa.html
构建实体类
@Entity(name = "t_book")
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "book_name")
private String name;
private String author;
//省略 getter/setter
}
public interface BookRepository extends JpaRepository<Book,Long> {
}
这里一个是配置了一个实体类 Book,另一个则是配置了一个 BookRepository ,项目启动成功后,框架会根据 Book 类的定义,在数据库中自动创建相应的表,BookRepository 接口则是继承自 JpaRepository ,JpaRepository 中自带了一些基本的增删改查方法。
好了,代码写完了。
啥?你好像啥都没写啊?是的,啥都没写,啥都不用写,一个 RESTful 风格的增删改查应用就有了,这就是 Spring Boot 的魅力!
测试
此时,我们就可以启动项目进行测试了,使用 POSTMAN 来测试(大家也可以自行选择趁手的 HTTP 请求工具)。
此时我们的项目已经默认具备了一些接口,我们分别来看:
根据 id 查询接口
这个接口表示根据 id 查询某一本书:
分页查询
这是一个批量查询接口,默认请求路径是类名首字母小写,并且再加一个 s 后缀。这个接口实际上是一个分页查询接口,没有传参数,表示查询第一页,每页 20 条数据。
查询结果中,除了该有的数据之外,也包含了分页数据:
分页数据中:
- size 表示每页查询记录数
- totalElements 表示总记录数
- totalPages 表示总页数
- number 表示当前页数,从0开始计
如果要分页或者排序查询,可以使用 _links 中的链接。 http://127.0.0.1:8080/books?page=1&size=3&sort=id,desc
。
添加
也可以添加数据,添加是 POST 请求,数据通过 JSON 的形式传递,如下:
添加成功之后,默认会返回添加成功的数据。
修改
修改接口默认也是存在的,数据修改请求是一个 PUT 请求,修改的参数也是通过 JSON 的形式传递:
默认情况下,修改成功后,会返回修改成功的数据。
删除
当然也可以通过 DELETE 请求根据 id 删除数据:
删除成功后,是没有返回值的。
不需要几行代码,一个基本的增删改查就有了。
这些都是默认的配置,这些默认的配置实际上都是在 JpaRepository 的基础上实现的,实际项目中,我们还可以对这些功能进行定制。
查询定制
最广泛的定制,就是查询,因为增删改操作的变化不像查询这么丰富。对于查询的定制,非常容易,只需要提供相关的方法即可。例如根据作者查询书籍:
public interface BookRepository extends JpaRepository<Book,Long> {
List<Book> findBookByAuthorContaining(@Param("author") String author);
}
注意,方法的定义,参数要有 @Param 注解。
定制完成后,重启项目,此时就多了一个查询接口,开发者可以通过 http://localhost:8080/books/s... 来查看和 book 相关的自定义接口都有哪些:
查询结果表示,只有一个自定义接口,接口名就是方法名,而且查询结果还给出了接口调用的示例。我们来尝试调用一下自己定义的查询接口:
开发者可以根据实际情况,在 BookRepository 中定义任意多个查询方法,查询方法的定义规则和 Jpa 中一模一样(不懂 Jpa 的小伙伴,可以参考 干货|一文读懂 Spring Data Jpa!,或者在松哥个人网站 www.javaboy.org 上搜索 JPA,有相关教程参考)。但是,这样有一个缺陷,就是 Jpa 中方法名太长,因此,如果不想使用方法名作为接口名,则可以自定义接口名:
public interface BookRepository extends JpaRepository<Book, Long> {
@RestResource(rel = "byauthor",path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
}
@RestResource 注解中,两个参数的含义:
- rel 表示接口查询中,这个方法的 key
-
path 表示请求路径
这样定义完成后,表示接口名为 byauthor ,重启项目,继续查询接口:
除了 rel
和 path
两个属性之外, @RestResource
中还有一个属性, exported
表示是否暴露接口,默认为 true
,表示暴露接口,即方法可以在前端调用,如果仅仅只是想定义一个方法,不需要在前端调用这个方法,可以设置 exported
属性为 false
。
如果不想暴露官方定义好的方法,例如根据 id
删除数据,只需要在自定义接口中重写该方法,然后在该方法上加 @RestResource
注解并且配置相关属性即可。
public interface BookRepository extends JpaRepository<Book, Long> {
@RestResource(rel = "byauthor",path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
@Override
@RestResource(exported = false)
void deleteById(Long aLong);
}
另外生成的 JSON 字符串中的集合名和单个 item
的名字都是可以自定义的:
@RepositoryRestResource(collectionResourceRel = "bs",itemResourceRel = "b",path = "bs")
public interface BookRepository extends JpaRepository<Book, Long> {
@RestResource(rel = "byauthor",path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
@Override
@RestResource(exported = false)
void deleteById(Long aLong);
}
path
属性表示请求路径,请求路径默认是类名首字母小写+s,可以在这里自己重新定义。
其他配置
最后,也可以在 application.properties 中配置 REST 基本参数:
spring.data.rest.base-path=/api
spring.data.rest.sort-param-name=sort
spring.data.rest.page-param-name=page
spring.data.rest.limit-param-name=size
spring.data.rest.max-page-size=20
spring.data.rest.default-page-size=0
spring.data.rest.return-body-on-update=true
spring.data.rest.return-body-on-create=true
配置含义,从上往下,依次是:
- 给所有的接口添加统一的前缀
- 配置排序参数的 key ,默认是 sort
- 配置分页查询时页码的 key,默认是 page
- 配置分页查询时每页查询页数的 key,默认是size
- 配置每页最大查询记录数,默认是 20 条
- 分页查询时默认的页码
- 更新成功时是否返回更新记录
- 添加成功时是否返回添加记录
这是 Spring Data Rest 的一个简单用法,接下来我们来看如何给这个生成的文档。
4.2 生成接口文档
对于这种你都没看到接口的,我们只需要添加如下依赖,就可以自动生成 API 文档了,如下:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-data-rest</artifactId>
<version>1.6.9</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
生成的接口文档如下:
5. 结合 Actuator
在之前的 Spring Boot 教程中,松哥还和大家介绍过 Spring Boot 中的 actuator,这个工具可以自行生成项目运行数据的端点(endpoints),如果想把这些端点也纳入到 SpringDoc 中来,那么只需要添加如下配置即可:
springdoc.show-actuator=true
至于 SpringDoc 会显示多少个 Actuator 端点出来,那就要看 Actuator 暴露出来多少端点了,最终显示效果如下:
不过这里还有一个玩法!
SpringDoc 扮演的角色毕竟不是业务功能,而是项目的辅助功能,所以,我们可以将之从业务中剥离,放到 Actuator 中,毕竟 Actuator 专干这种事。那么只需要增加如下两个配置即可:
springdoc.use-management-port=true
management.endpoints.web.exposure.include=openapi, swagger-ui
management.server.port=9090
配置完成后,将来就可以在 Actuator 中去查看接口文档和对应的页面了,访问地址是:
6. 切换到 Swagger
如果你在项目中已经使用了 Swagger 了,那么也可以非常方便的切换到 SpringDoc 上面来,切换的时候,首先引入 SpringDoc 依赖:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
Swagger 和 SpringDoc 注解的对应关系如下:
- @Api → @Tag
- @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
- @ApiImplicitParam → @Parameter
- @ApiImplicitParams → @Parameters
- @ApiModel → @Schema
- @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
- @ApiModelProperty → @Schema
- @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
- @ApiParam → @Parameter
- @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
以前我们在 Swagger 中配置接口扫描的方式如下:
@Bean
public Docket publicApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
.paths(PathSelectors.regex("/public.*"))
.build()
.groupName("springshop-public")
.apiInfo(apiInfo());
}
@Bean
public Docket adminApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
.paths(PathSelectors.regex("/admin.*"))
.apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
.build()
.groupName("springshop-admin")
.apiInfo(apiInfo());
}
现在在 SpringDoc 中则按照如下方式进行配置即可(还可以按照注解去标记需要生成接口文档的方法):
@Configuration
public class SpringDocConfig {
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("springshop-public")
.pathsToMatch("/public/**")
.build();
}
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("springshop-admin")
.pathsToMatch("/admin/**")
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(RequestMapping.class))
.build();
}
}
当然,如果你并不需要对接口文档进行分组,那么也可以不使用 Java 配置,直接在 application.properties 中进行配置即可:
springdoc.packages-to-scan=org.javaboy.spring_doc.controller
springdoc.paths-to-match=/**
在 SpringDoc 中,如果你想配置 Swagger UI,则可以通过如下方式进行配置:
@Bean
OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("江南一点雨")
.description("Spring Boot 教程")
.version("v0.0.1")
.license(new License().name("Apache 2.0").url("http://www.javaboy.org")))
.externalDocs(new ExternalDocumentation()
.description("一些描述信息")
.url("https://github.com/lenve/vhr"));
}
好啦,常见用法大概就是这样,感兴趣的小伙伴可以去试试哦~关于 SpringDoc 的更多玩法,大家也可以参考官方文档:springdoc.org。