Spring Boot使用OpenAPI规范

在WEB领域里面，随着前后端分离，后端的HTTP接口便需要去维护一份大而全的Rest API，一个比较靠谱的文档工具是必不可少的。

迭代中的系统，随着时间的推移，以前提供出去的接口，很快就会发生变化。同时去维护代码和接口文档，意味着工作量的增加，或者种种其他原因，导致接口和文档的不同步是家常便饭的事情。

那么如果文档是由代码注释或者类似的方式生成，便可以在一定程度上避免这样的事情。常规的方案就是使用OpenAPI规范，它的前身即大名鼎鼎的Swagger。

如何使用

首先引入依赖

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.7</version>
  </dependency>
</dependencies>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>2.1.3.RELEASE</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

启动后访问地址 ip:port/swagger-ui/index.html , 可以看到一个Swagge UI的界面，即可正常进行使用了，默认打开示例。

注解

OpenAPI 是Swagger v3 ，所使用的注解跟原来的有所区别。主要的一些注解如以下表格

交互式文档

ip:port/swagger-ui/index.html 开启的时候使用的是默认示例。当我们给自己的接口写上加上OpenAPI的注解后，可以在Swagger界面的Explore框里面填入/v3/api-docs/点击explore按钮来查看。

点开其中一个方法，有具体的描述，方法的用处，参数和返回等上述注解中所定义的内容。

点击右上角的【try it out】按钮，则可以出现一个模拟请求的交互界面。

填入对应的参数，然后点击【Execute】按钮即可发起请求，然后在Responses看到对应的结果。同时也有Curl和Request URL给出，可以比较方便地复制到其他地方使用。

这种交互性的文档对于开发者来说比较有用，可以不用再自己去装一个postman来做模拟请求。

对于有条件的团队，有自己的文档平台，那么可以通过 ip:port//v3/api-docs/ 来获取文档的内容，Swagger也只是提供了一个交互界面来呈现文档。

结语

OpenAPI规范，定义了一套文档标准，并提供了默认实现以及方便使用的交互性文档界面。缺点是注解对应用的侵入性比较大，使用过程中亦需要关注安全问题。