【Springdoc-openapi】基于SpringBoot3.3.x版本③集成Springdoc

摘要

在微服务开发过程中，后端同学会写各种API，每写一个API，都需要相应的API文档，前端同学需要根据API文档进行开发、联调，其它后端同学也需要通过API文档了解系统设计以及方便排查问题。

关于API文档的工具有很多，比如常用的Swagger、Apifox等等，本文主要介绍Springdoc开源库，它与Spring Boot框架体系的集成更显丝滑。

本着"最新"原则，这篇文章依然采用最新版的Spring Boot 3.3.4，最新版springdoc-openapi-starter 2.6.0，最新版springdoc-openapi 1.8.0，OpenJDK最新LTS版21，IntelliJ IDEA最新社区版2024.2.3。

本地开发环境说明

开发用到的主要框架、工具版本如下

开发依赖	版本
Spring Boot	3.3.4
springdoc-openapi-starter	2.6.0
springdoc-openapi	1.8.0
JDK	21
IntelliJ IDEA	2024.2.3

pom.xml

• 如果依赖spring-boot-starter-web并且需要访问swagger-ui，则引入springdoc-openapi-starter-webmvc-ui
• 如果依赖spring-boot-starter-web并且只需要访问OpenAPI endpoints，则引入springdoc-openapi-starter-webmvc-api
• 如果依赖spring-boot-starter-webflux并且需要访问swagger-ui，则引入springdoc-openapi-starter-webflux-ui
• 如果依赖spring-boot-starter-webflux并且只需要访问OpenAPI endpoints，则引入springdoc-openapi-starter-webflux-api

pom依赖如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.4</version>
        <relativePath/>
    </parent>

    <artifactId>wen3-framework-apidoc-springdoc-demo</artifactId>

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

如果要把actuator加入swagger文档，则增加以下依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

如果要把Javadoc生成swagger文档，则增加以下依赖

<!-- 从Javadoc注释生成Swagger文档 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
    <version>${springdoc-openapi-javadoc.version}</version>
    <!--包含依赖 ：therapi-runtime-javadoc-->
</dependency>

Controller演示类

为了演示API分组的效果，在3个不同的包下新建3个不同的Controller类

• com.wen3.springdoc.demo.controller.DemoController

package com.wen3.springdoc.demo.controller;

import io.swagger