SpringBoot3整合swagger（springdoc-openapi）

目录

• 传送门
• 一、前言
• 二、入门配置
• • 1、改pom
  • 2、写Controller案例
  • • 2.1不用其他配置
    • 2.2注意注释区别
    • 3、检验测试
    • 三、加强配置
    • • 1、方式一：引入OpenApiConfig
      • 2、方式二：配置application.yml

        传送门

        SpringMVC的源码解析（精品）

        Spring6的源码解析（精品）

        SpringBoot3框架（精品）

        MyBatis框架（精品）

        MyBatis-Plus

        SpringDataJPA

        SpringCloudNetflix

        SpringCloudAlibaba（精品）

        Shiro

        SpringSecurity

        java的LOG日志框架

        Activiti（敬请期待）

        JDK8新特性

        JDK9新特性

        JDK10新特性

        JDK11新特性

        JDK12新特性

        JDK13新特性

        JDK14新特性

        JDK15新特性

        JDK16新特性

        JDK17新特性

        JDK18新特性

        JDK19新特性

        JDK20新特性

        JDK21新特性

        其他技术文章传送门入口

        一、前言

        网上查看了大量资料，发现SpringBoot3+jdk17的情况下，swagger的V2和V3都是不行的。果断转用spring官方出品的springdoc-openapi。在使用springdoc-openapi的时候也有很多坑，首先springdoc-openapi的v1.x.x版本也是不行的，springdoc-openapi的版本必须是v2.x.x以上。

        官网链接：https://springdoc.org/v2/

        二、入门配置

        1、改pom

        我的示例Demo项目只引入了很简单的一些东西。下面的两个jar包，第一个是必须导入的，而且一定得在2版本以上。

                            org.springdoc            springdoc-openapi-starter-webmvc-ui            2.1.0                            org.springdoc            springdoc-openapi-starter-webmvc-api            2.1.0        

        2、写Controller案例

        2.1不用其他配置

        OpenApiConfig这种配置完全可以不用做，application.yml也可以完全不用配置。默认引入pom文件以后，写好Controller就可以用了。

        package com.zt.controller;import com.zt.framework.web.CommonResult;import io.swagger.v3.oas.annotations.Operation;import io.swagger.v3.oas.annotations.tags.Tag;import lombok.extern.slf4j.Slf4j;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.RestController;@RestController@Slf4j@Tag(name = "hello")public class HelloController {    @GetMapping("/hello")    @Operation(summary = "hello", description = "hello")    public CommonResult hello(){        int a = 1/0;        log.info("hello!!!");        return CommonResult.successMessage("hello!!!");    }}

        2.2注意注释区别

        @Api -> @Tag@ApiIgnore -> @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @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")

        3、检验测试

        访问地址swagger-ui风格：

        http://server:port/context-path/swagger-ui.html

        访问地址swagger-json风格：

        http://server:port/context-path/v3/api-docs

        我这边个人swagger-ui风格地址：

        http://localhost:8888/swagger-ui/index.html

        我这边个人swagger-json风格地址：

        http://localhost:8888/v3/api-docs

        导入apifox也完全没问题，本身就是OpenApi3

        三、加强配置

        1、方式一：引入OpenApiConfig

        package com.zt.framework.config;import io.swagger.v3.oas.models.Components;import io.swagger.v3.oas.models.ExternalDocumentation;import io.swagger.v3.oas.models.OpenAPI;import io.swagger.v3.oas.models.info.Contact;import io.swagger.v3.oas.models.info.Info;import io.swagger.v3.oas.models.info.License;import io.swagger.v3.oas.models.media.StringSchema;import io.swagger.v3.oas.models.parameters.Parameter;import io.swagger.v3.oas.models.security.SecurityRequirement;import io.swagger.v3.oas.models.security.SecurityScheme;import org.springdoc.core.configuration.SpringDocConfiguration;import org.springdoc.core.models.GroupedOpenApi;import org.springframework.boot.autoconfigure.AutoConfigureBefore;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import java.util.Collections;@Configurationpublic class OpenApiConfig {    @Bean    public OpenAPI openApi() {        return new OpenAPI()                .info(new Info()                        .title("文档标题")                        .description("文档描述")                        .contact(new Contact().name("作者").email("邮箱").url("可以写你的博客地址或不填"))                        .version("v2.0"));    }}

        参考大神链接：https://blog.csdn.net/m88997766/article/details/130026004

        这边还能配置很多东西。常见的api分组等等，参考上面大神链接。

        2、方式二：配置application.yml

        springdoc:  api-docs:    # 是否开启接口文档    enabled: true  swagger-ui:    # 持久化认证数据，如果设置为 true，它会保留授权数据并且不会在浏览器关闭/刷新时丢失    persistAuthorization: true

        yml这边应该还有很多其他配置。详细见前言的官网说明。