Springboot整合Swagger3全注解配置(springdoc-openapi-ui)

2024-04-02 19:55

短信预约 -IT技能 免费直播动态提醒

一、创建Springboot项目，引入pom依赖

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

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

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.12</version>
        </dependency>

        <!-- 只需要引入这一个依赖就行了 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.5.5</version>
        </dependency>

二、配置类请求头携带token

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;

@OpenAPIDefinition(
        info = @Info(
                title = "Swagger3",
                version = "1.0",
                description = "Swagger3使用演示",
                contact = @Contact(name = "TOM")
        ),
        security = @SecurityRequirement(name = "JWT"),
        externalDocs = @ExternalDocumentation(description = "参考文档",
                url = "https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations"
        )
)
@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "bearer", in = SecuritySchemeIn.HEADER)
public class Swagger3Config {

}

@OpenAPIDefinition全局只能定义一个，主要配置文档信息和安全配置，这里列举了常用的请求头携带token的安全配置模式
@OpenAPIDefinition下的info属性配置文档信息
@OpenAPIDefinition下的security配置认证方式，name属性引入自定义的认证模式
@SecurityScheme注解就是自定义的认证模式，配置请求头携带token

三、配置文件

server:
  port: 8080

springdoc:
  api-docs:
    #是否开启文档功能
    enabled: true
    #swagger后端请求地址
    path: /api-docs
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/test会自动重定向到swagger页面
    path: /test
  #包扫描路径
  packages-to-scan: com.hello.controller,com.hello.dto
  #这里定义了两个分组，可定义多个，也可以不定义
  group-configs:
      #分组名
    - group: admin
      #按路径匹配
      pathsToMatch: /admin
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<T>(200, "操作成功", data);
    }

    
    public static <T> CommonResult<T> failed(String message) {
        return new CommonResult<T>(400, message, null);
    }
}

package com.hello.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;

@Schema(name="User",description ="用户信息" )
@Data
@AllArgsConstructor
public class User {
    @Schema(name = "name",description = "姓名")
    private String name;
    @Schema(name = "age",description = "年龄")
    private int age;
}