SpringBoot 3.2.0 基于SpringDoc接入OpenAPI实现接口文档-编程知识

SpringBoot 3.2.0 基于SpringDoc接入OpenAPI实现接口文档

依赖版本

JDK 17
Spring Boot 3.2.0
SpringDoc 2.3.0

工程源码：Gitee

导入依赖

<properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><springdoc.version>2.3.0</springdoc.version>
</properties><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><version>${springdoc.version}</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency>
</dependencies>

创建SpringDoc配置文件

application.yml 配置

server:port: 8080# ======== SpringDocs文档配置 ========
springdocs:title: SpringBoot3.2.0 API Docsdescription: SpringBoot3 + OpenAPI Docsversion: 0.0.1scheme: Bearerheader: Authorization

OpenAPI配置文件

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;@Component
@ConfigurationProperties(prefix = "springdocs")
@Setter
@Getter
public class SpringDocsProperties {private String title;private String description;private String version;private String header;private String scheme;
}

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import jakarta.annotation.Resource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** SpringDoc配置文件*/
@Configuration
public class SpringDocConfig {@Resourceprivate SpringDocsProperties springDocsProperties;@Beanpublic OpenAPI openApi() {return new OpenAPI()// 文档描述信息.info(new Info().title(springDocsProperties.getTitle()).description(springDocsProperties.getDescription()).version(springDocsProperties.getVersion()))// 添加全局的header参数.addSecurityItem(new SecurityRequirement().addList(springDocsProperties.getHeader())).components(new Components().addSecuritySchemes(springDocsProperties.getHeader(), new SecurityScheme().name(springDocsProperties.getHeader()).scheme(springDocsProperties.getScheme()).bearerFormat("JWT").type(SecurityScheme.Type.HTTP)));}
}

OpenAPI 与 Swagger的 API对应

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")