Spring Boot整合Swagger3(OpenAPI3)生成接口文档

都说好记性不如烂笔头,每天写一点,从量变到质变的开始!废话不多说,以下所有内容均来自本人实际操作:

1.为什么使用Swagger3(OpenAPI3)?

• swagger官方文档介绍的功能太过复杂,作为一个后端开发,我们往往只需要用它来自动生成接口文档,而Swagger2早就不维护了,因此通过这篇博客找到了springdoc官网
• springdoc-openapi Java库有助于使用Spring Boot项目自动生成API文档.springdoc-openapi的工作原理是在运行时检查应用程序,以基于spring配置,类结构和各种注释来推断API语义,自动生成JSON / YAML和HTML格式的API文档,可以使用swagger-api注释通过注释来完成本文档.

2.新建Spring Boot项目,添加OpenAPI依赖(不需要其他配置)

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

3.启动项目访问试试(http://localhost:8080/swagger-ui.html)

4. 修改yml配置文件,自定义swagger配置

4.1 自定义swagger访问html首页

springdoc:
  swagger-ui:
    path: /swagger/index.html

4.2 禁用springdoc-openapi

springdoc:
  api-docs:
    enabled: false

4.3 禁用swagger-ui

springdoc:
  swagger-ui:
    enabled: false

 4.4 除了来自swagger-annotations的@Hidden注释之外,还可以使用程序包或路径配置来限制生成的OpenAPI描述

# Packages to include
springdoc.packagesToScan=com.package1, com.package2
# Paths to include
springdoc.pathsToMatch=/v1, /api/balance/**

4.5 springdoc-openapi核心属性

4.6