springboot集成springdoc接口文档生成

maven 引入

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.9</version>
        </dependency>

配置

不需要任何配置即可使用。（没特殊要求的，直接跳过此步骤。）

默认是启用状态，可以在配置中停用。（spring-boot配置文件，例：application.properties）

springdoc.api-docs.enabled=true //默认为true，配置为false则是停用

 

其他可配置属性可以 输入springdoc后智能提示出来，具体可查看配置注释。

 

使用

controller相关配置，与swagger2完全不一样，后面有相应的对应说明。

 

实体类相关配置：

默认swagger-ui访问地址

http://ip:port/swagger-ui/index.html

效果：

 

与swagger2属性对比

(之前没用过swagger2，可忽略此说明。）

 

 

ui及使用优化

建议搭配其他的ui工具进行使用，推荐apifox。可以直接导入api-docs。

如果使用apifox,就可以将swagger-ui依赖去掉，减少包体积，这个ui包有3M多，还是挺大的，而且也很难用。

api-docs默认地址http://ip:port/v3/api-docs

 

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.9</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-ui</artifactId>
                    <groupId>org.webjars</groupId>
                </exclusion>
            </exclusions>
        </dependency>

apifox阅读更清晰

 

 

api-docs和swagger-ui的关系：

简单说下个人理解的api-docs和swagger-ui的关系：

api-docs是根据openapi规范生成的json文档。

swagger-ui是根据api-docs生成的可视化的页面。

所以api-docs才是根本，ui可以随意选择自己喜欢的。

参考文档

https://springdoc.org/

https://blog.csdn.net/Aplumage/article/details/124961459

有不对的地方，还请指正。