====== 前言 ======
^概念  ^意思  ^
|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

相关配置： https://springdoc.org/index.html#swagger-ui-properties
<code>
引入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
</code>


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