当前位置：首页 > news >正文

springboot2.x集成swagger api(springdoc-openapi-ui)

news 2025/9/3 12:33:46

1、引入依赖

<properties><!-- 统一管理版本号 --><swagger-models.version>2.2.21</swagger-models.version><openapi-ui.version>1.6.14</openapi-ui.version><springdoc.version>1.6.14</springdoc.version></properties>
<dependencyManagement><dependencies><!-- 添加 springdoc 依赖 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>${openapi-ui.version}</version> <!-- 选择与你Spring Boot版本匹配的版本 --></dependency><dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-models-jakarta</artifactId><version>${swagger-models.version}</version><scope>compile</scope></dependency><!--以下这个不知道要不要引用，如果试了不行再放开他-->
<!--<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webmvc-ui</artifactId><version>${springdoc.version}</version></dependency>
--></dependencies></dependencyManagement>

2、编写一个SwaggerConfig的配置类

import io.swagger.v3.oas.models.Components;
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.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SwaggerConfig {/** 系统基础配置 */@Autowiredprivate Config config;/*** 自定义的 OpenAPI 对象*/@Beanpublic OpenAPI customOpenApi(){return new OpenAPI().components(new Components()// 设置认证的请求头.addSecuritySchemes("apikey", securityScheme())).addSecurityItem(new SecurityRequirement().addList("apikey")).info(getApiInfo());}@Beanpublic SecurityScheme securityScheme(){return new SecurityScheme().type(SecurityScheme.Type.APIKEY).name("Authorization").in(SecurityScheme.In.HEADER).scheme("Bearer");}/*** 添加摘要信息*/public Info getApiInfo(){return new Info()// 设置标题.title("登录服务_接口文档")// 描述.description("描述：登录服务")// 作者信息.contact(new Contact().name(config.getName()))// 版本.version("版本号:" + config.getVersion());}}

package com.cosco.gzsic.config;import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;@Data
@Component
@ConfigurationProperties(prefix = "biz")
public class Config {private String name;private String version;
}

3、编写接口，使用注解

import com.cosco.gzsic.config.Config;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/demo")
@Tag(name = "测试管理相关接口", description = "提供测试接口")
public class DemoController {@Autowiredprivate Config config;@Operation(summary = "提供测试信息", description = "提供参数化获取测试信息")@GetMapping("/getDemo")public String hello(@Parameter (description = "用户名",//参数描述required = true) String userName){return "hello word 9090："+userName+"--" + config.getName() + ":" + config.getVersion();}
}