不用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 查询接口

• http://127.0.0.1:8080/books/{id}

这个接口表示根据 id 查询某一本书：

分页查询

• http://127.0.0.1:8080/books

这是一个批量查询接口，默认请求路径是类名首字母小写，并且再加一个 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(&quot;author&quot;) String author);
}


注意，方法的定义，参数要有 @Param 注解。

定制完成后，重启项目，此时就多了一个查询接口，开发者可以通过 http://localhost:8080/books/search 来查看和 book 相关的自定义接口都有哪些：

查询结果表示，只有一个自定义接口，接口名就是方法名，而且查询结果还给出了接口调用的示例。我们来尝试调用一下自己定义的查询接口：

开发者可以根据实际情况，在 BookRepository 中定义任意多个查询方法，查询方法的定义规则和 Jpa 中一模一样（不懂 Jpa 的小伙伴，可以参考

干货|一文读懂 Spring Data Jpa！

，或者在松哥个人网站 www.javaboy.org 上搜索 JPA，有相关教程参考）。但是，这样有一个缺陷，就是 Jpa 中方法名太长，因此，如果不想使用方法名作为接口名，则可以自定义接口名：

public interface BookRepository extends JpaRepository<Book, Long> {
 @RestResource(rel = &quot;byauthor&quot;,path = &quot;byauthor&quot;)
 List<Book> findBookByAuthorContaining(@Param(&quot;author&quot;) 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 = &quot;byauthor&quot;,path = &quot;byauthor&quot;)
 List<Book> findBookByAuthorContaining(@Param(&quot;author&quot;) 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 = &quot;byauthor&quot;,path = &quot;byauthor&quot;)
 List<Book> findBookByAuthorContaining(@Param(&quot;author&quot;) 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 中去查看接口文档和对应的页面了，访问地址是：

• http://localhost:9090/actuator/swagger-ui/index.html

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。