SpringBoot集成SpringDoc和Swagger3

概念

SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有1.7K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目

引入包

 <!--springdoc 官方Starter-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.6</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>2.2.0</version>
        </dependency>

方案一 bearer token

配置

/**
 * SpringDoc API文档相关配置
 */
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info().title("Edevp-Stpre API")
                        .description("SpringDoc API 演示")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("https://edevp.cn")))
                .externalDocs(new ExternalDocumentation()
                        .description("Edevp-Stpre")
                        .url("http://www.edevp.cn"))
                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
                .components(new Components()
                        .addSecuritySchemes(HttpHeaders.AUTHORIZATION,
                                new SecurityScheme()
                                        .name(HttpHeaders.AUTHORIZATION)
                                        .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
               // .schemaRequirement(HttpHeaders.AUTHORIZATION, this.securityScheme());
    }
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("org")
                .pathsToMatch("/org/**")
                .build();
    }
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("storage")
                .pathsToMatch("/storage/**")
                .build();
    }
}

controller

@Slf4j
@Tag(name = "库存管理")
@RestController
@RequestMapping("/storage")
@AllArgsConstructor
public class StoreController {

	private final StoreService storeService;

	@Operation(summary = "新增")
	@PutMapping("")
	R add(HttpServletRequest request, @Validated @Parameter(description = "商品实体" ,name="data", required = true) @RequestBody StoreGoodsInfoDTO data)
	{
		String token = request.getHeader("Authorization");
		return R.ok(token);
	}

}

实体

@Schema(description = "商品库存信息")
public class StoreGoodsInfoDTO {
	private String id;
	@Schema(description = "数量")
	@NotNull
	private Integer count;
}

访问

token

调用时可以看到设置的token

方案二：

配置

@Bean
    public OpenAPI customOpenAPI() {
        Contact contact= new Contact();
        contact.setName("eebd");

        OpenAPI openAPI = new OpenAPI().info(new Info().title("Title"));
        // oauth2.0 password
        openAPI.schemaRequirement(HttpHeaders.AUTHORIZATION, this.securityScheme());
        //全局安全校验项，也可以在对应的controller上加注解SecurityRequirement
        openAPI.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));

        return openAPI;
    }

    private SecurityScheme securityScheme() {
        SecurityScheme securityScheme = new SecurityScheme();
        //类型
        securityScheme.setType(SecurityScheme.Type.APIKEY);
        //请求头的name
        securityScheme.setName(HttpHeaders.AUTHORIZATION);
        //token所在未知
        securityScheme.setIn(SecurityScheme.In.HEADER);
        return securityScheme;
    }

token

引入edevp-common-swagger-biz

配置

# 单体部署，如果要关闭需要如下
springdoc:
  api-docs:
    enabled: true

# swagger 配置，单体应用需要结合
swagger:
  enabled: true
  title: Edevp Swagger API
  scope: server

如果关闭开启或关闭，需要同时修改上面两个，同时开启之后自定义的swagger会覆盖springdoc的配置。如果只开启springdoc，没有开启swagger.enable则使用默认配置。