前言

概念	意思
OpenAPI	有别于专有API:自己服务后端接口专门暴露给自己网站使用的, 它是暴露出来给其他公司应用或网站使用的API
OAS3	Open API Specification 3的缩写，即OpenAPI规范（第三版本）由https://openapis.org于2017年7月发布，目前最新的是3.1： https://spec.openapis.org/oas/v3.1.0
Swagger UI	官网https://swagger.io/, 有好几个开源产品，其中swagger-ui: https://swagger.io/tools/swagger-ui/ 比较好用，产品本质：一个index.html + 一堆静态文件. 开源地址：https://github.com/swagger-api/swagger-ui，最新版3.51.1
springfox	封装swagger-ui做得java实现,代码：https://github.com/springfox/springfox
springdoc-openapi	封装swagger-ui做得java实现,代码：https://github.com/springdoc/springdoc-openapi
swagger-bootstrap-ui	封装swagger-ui做得java实现,代码： https://github.com/xiaoymin/swagger-bootstrap-ui 已改名为knife4j

因为google, facebook,tencent 等这些大公司，已经不再是只做一些暴露给自己公司应用去使用的专有API了，也已经有了很多Open API。而这种需求越来越多，于是大家有了Open API的规范。

而大家都有自动根据代码生成文档的需求。所以swagger做了一套很好的UI界面交互的产品: swagger-ui.

为了能让他java开发，很容易直接使用上，并且很好的兼容springboot之类的。不同组织或个人分别开发了： springfox, springdoc-openapi, knife4j

关于技术选择

2020年年初，我选择了springfox的2.8版本，后来升级为2.9.2。但在开发的过程中，仍然遇到解决不了的困难，比如：无法全局设置cookie

2021年七月，我尝试在新的项目中使用springfox 3.0.0。据说是可以全局设置cookie，但仍然会遇到nullpoint exception。在艰难的探索中，无意间发现了springdoc-openapi

经过对比，springdoc-openapi更加优于springfox和knife4j。最终选择使用它作为今后个人项目中的文档工具。

使用springdoc-openapi

参看 demo: https://springdoc.org/#demos

引入jar
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.5.9</version>
   </dependency>

做些配置：
#开启swagger-ui
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui/index.html
#不显示默认的例子
springdoc.swagger-ui.disable-swagger-default-url=true

#配置扫描目录
springdoc.packages-to-scan=com.xiaosq.projectx.web.controller

主要使用上的优势

springdoc	springfox
@Schema支持默认值，目前仅对String类型生效	@ApiModelProperty不支持设置默认值
这个目前看到的代码更新更活跃，最新版本时今年4月的	最新版本是去年，前年的。有点悬
很好的支持cookie和header	也能支持，只是不太好

Table of Contents

前言

关于技术选择

使用springdoc-openapi

主要使用上的优势