springdoc-openapi主页翻译

原文地址

springdoc-openapi是一个基于spring-boot的OpenAPI 3类库。

简介

springdoc-openapi java库帮助基于spring boot开发的项目自动生成API文档。
springdoc-openapi 通过在运行时检查应用程序，根据spring配置、类结构和各种注解推断API语义。

自动生成JSON/YAML和HTML格式的API文档。这个文档的所有内容都可以使用swagger-api注解来编写。

本库支持:

OpenAPI 3
Spring-boot (v1 and v2)
JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
Swagger-ui
OAuth 2

以下是本库的介绍视频(youtube视频):

Watch the video

Code

这是一个社区驱动的项目, 并不是Spring官方维护的项目。

入门

overview

集成`Spring-boot`和本类库(包含界面))

自动将swagger-ui部署到spring-boot应用程序中。
文档将以 HTML 格式提供，使用官方的 swagger-ui jars。
通过http://server:port/context-path/swagger-ui.html打开Swagger UI页面，而OpenAPI的描述将在以下json格式的url中提供：http://server:port/context-path/v3/api-docs。
- server: 服务器名称或IP
- port: 服务器端口
- context-path: 应用程序的上下文路径
文档也可以以yaml格式提供，路径如下：http://server:port/context-path/v3/api-docs.yml。
将库添加到你的项目依赖列表中（不需要额外的配置）。
```
   org.springdoc
   springdoc-openapi-ui
   1.4.8
```
这一步是可选的。对于HTML格式的swagger文档的自定义路径，在你的spring-boot配置文件中添加一个自定义springdoc属性。
```
 # swagger-ui custom path
 springdoc.swagger-ui.path: /swagger-ui.html
```
json格式的文档将在以下网址上提供：http://server:port/context-path/v3/api-docs。
服务器。服务器名称或IP
端口。服务器端口
的上下文路径。应用程序的上下文路径
文档也将以yaml格式提供，路径如下：/v3/api-docs.yml。
将该库添加到你的项目依赖列表中。(不需要额外的配置)

集成`Spring-boot`和本类库(不含界面))

文档可以通过http://server:port/context-path/v3/api-docs访问(json格式)
- server: 服务器名称或IP
- port: 服务器端口
- context-path: 应用程序的上下文路径
文档也可以以yaml格式提供，路径如下：http://server:port/context-path/v3/api-docs.yml。

将库添加到你的项目依赖列表中（不需要额外的配置）。


   org.springdoc
   springdoc-openapi-webmvc-core
   1.4.8

这一步是可选的。对于HTML格式的swagger文档的自定义路径，在你的spring-boot配置文件中添加一个自定义springdoc属性。
```
 # swagger-ui custom path
 springdoc.api-docs.path: /api-docs
```

WildFly 用户需要再加上此依赖才能正常使用swagger-ui:


  org.webjars
  webjars-locator-jboss-vfs
  0.1.0

其他设置

添加API信息和安全文档

该库使用spring-boot应用自动配置机制来扫描spring beans中的以下注解: OpenAPIDefinition和Info。
这些注解定义了API的以下信息: 标题、版本、许可、安全、服务器、标签、安全和外部文档。
为了获得更好的文档生成性能，
请在spring管理的Bean中声明@OpenAPIDefinition和@SecurityScheme注解。

使用`@ControllerAdvice`进行REST错误处理

要自动生成文档，请确保所有方法都使用注解声明HTTP代码响应。@ResponseStatus

禁用 springdoc-openapi 端点。

为了禁用springdoc-openapi端点(默认情况下是/v3/api-docs)，使用以下属性。

# Disabling the /v3/api-docs enpoint
springdoc.api-docs.enabled: false

禁用 swagger-ui

使用以下配置可以禁用swagger-ui界面:

# Disabling the swagger-ui
springdoc.swagger-ui.enabled: false

Swagger-ui 配置

The library supports the swagger-ui official properties:

https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

你需要将 swagger-ui 属性声明为 spring-boot 属性。所有这些属性都应该用以下前缀来声明：springdoc.swagger-ui。

选择要包含在文档中的`Rest Controllers`。

除了来自 swagger-annotations 的 @Hidden 注释，它还可以使用包或路径配置来限制生成的 OpenAPI 描述。

对于要包含的包列表，使用以下属性。

# Packages to include
springdoc.packagesToScan: com.package1, com.package2

For the list of paths to include, use the following property:
如果要包含指定的路径, 使用以下配置属性:

# Paths to include
springdoc.pathsToMatch=/v1, /api/balance/**

Spring-webflux 支持

   
      org.springdoc
      springdoc-openapi-webflux-ui
      1.4.8

Spring-webflux/WebMvc.fn 函数式编程支持

略

Spring Hateoas 支持

HATEOAS是Hypertext As The Engine Of Application State的缩写。在Richardson Maturity Model中, 它是REST的最高级形态。

Richardson 提出的 REST 成熟度模型把 REST 服务按照成熟度划分成 4 个层次：

第一个层次（Level 0）的 Web 服务只是使用 HTTP 作为传输方式，实际上只是远程方法调用（RPC）的一种具体形式。SOAP 和 XML-RPC 都属于此类。
第二个层次（Level 1）的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
第三个层次（Level 2）的 Web 服务使用不同的 HTTP 方法来进行不同的操作，并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源，HTTP DELETE 方法来删除资源。
第四个层次（Level 3）的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。

该模型将REST划作了由低到高四个等级，等级越高，RESTful就越成熟。

通过加入以下依赖, 可以支持Spring Hateoas:

   
      org.springdoc
      springdoc-openapi-hateoas
      1.4.8

Spring Data Rest 支持

   
      org.springdoc
      springdoc-openapi-data-rest
      1.4.8

Spring security 支持

   
      org.springdoc
      springdoc-openapi-security
      1.4.8

Kotlin 支持

   
      org.springdoc
      springdoc-openapi-kotlin
      1.4.8

Groovy 支持

   
      org.springdoc
      springdoc-openapi-groovy
      1.4.8

MAVEN插件介绍 springdoc-openapi-maven-plugin

springdoc-openapi-maven-plugin的目的是在构建期间生成json和yaml OpenAPI描述。
该插件在集成测试阶段工作，并生成OpenAPI描述。
该插件与spring-boot-maven插件一起工作。

你可以在集成测试阶段使用maven命令测试它。

mvn verify -Dspring.application.admin.enabled=true

为了使用这个功能，您需要在您的pom.xml的plugins部分添加插件声明。


    
     org.springframework.boot
     spring-boot-maven-plugin
     2.3.0.RELEASE
     
      
       pre-integration-test
       
        start
       
      
      
       post-integration-test
       
        stop
       
      
     
    
    
    
     org.springdoc
     springdoc-openapi-maven-plugin
     1.0
     
      
       integration-test
       
        generate

该插件的文档说明网址:

https://github.com/springdoc/springdoc-openapi-maven-plugin

Gradle插件介绍 springdoc-openapi-gradle-plugin

略

DEMO程序列表

Demo Spring Boot 2 Web MVC with OpenAPI 3.
Demo Spring Boot 2 WebFlux with OpenAPI 3.
Demo Spring Boot 1 Web MVC with OpenAPI 3.
Demo Spring Boot 2 WebFlux with Functional endpoints OpenAPI 3.
Demo Spring Boot 2 and Spring Hateoas with OpenAPI 3.

Branching

DEMO程序源码仓库

https://github.com/springdoc/springdoc-openapi-demos.git

依赖仓库

本库发布在maven中央仓库, maven坐标可以通过以下网址查到:

正式版本:

https://oss.sonatype.org/content/groups/public/org/springdoc/.

快照版本:

https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/.