SpringDoc基础配置和集成OAuth2登录认证教程

本期内容

1. 学会通过注解和Java代码的方式添加SpringDoc配置。
2. 在swagger-ui提供的页面上提供OAuth2登录认证，在集成Security的情况下便捷获取access_token并在请求时按照OAuth2规范携带。

为什么集成OAuth2登录认证？

现在大部分教程是在swagger-ui页面添加一个请求头，使用时先去获取一个token，然后再将获取的token填充至页面的token输入框内，如果是通过某个接口自己生成token的方式使用这种配置没什么太大问题，但是如果是通过OAuth2登录获取token时就比较麻烦，要填充token type和access token，所以在swagger-ui提供的页面中提供OAuth2登录的入口，OAuth2登录自动配置，一步到位。

配置方式说明

SpringDoc提供了两种方式来添加配置：

1. 注解
2. Java类的方式

注解

注解配置类

配置方式如下代码所示，详细内容请看代码中的注释

package com.example.config;import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.security.OAuthFlow;
import io.swagger.v3.oas.annotations.security.OAuthFlows;
import io.swagger.v3.oas.annotations.security.OAuthScope;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.security.SecuritySchemes;
import org.springframework.context.annotation.Configuration;/*** Spring Doc OpenApi 注解配置** @author vains*/
@Configuration
@OpenAPIDefinition(info = @Info(// 标题title = "${custom.info.title}",// 版本version = "${custom.info.version}",// 描述description = "${custom.info.description}",// 首页termsOfService = "${custom.info.termsOfService}",// licenselicense = @License(name = "${custom.license.name}",// license 地址url = "http://127.0.0.1:8080/example/test01")),// 这里的名字是引用下边 @SecurityScheme 注解中指定的名字，指定后发起请求时会在请求头中按照OAuth2的规范添加tokensecurity = @SecurityRequirement(name = "${custom.security.name}")
)
@SecuritySchemes({@SecurityScheme(// 指定 SecurityScheme 的名称(OpenAPIDefinition注解中的security属性中会引用该名称)name = "${custom.security.name}",// 指定认证类型为oauth2type = SecuritySchemeType.OAUTH2,// 设置认证流程flows = @OAuthFlows(// 设置授权码模式authorizationCode = @OAuthFlow(// 获取token地址tokenUrl = "${custom.security.token-url}",// 授权申请地址authorizationUrl = "${custom.security.authorization-url}",// oauth2的申请的scope(需要在OAuth2客户端中存在)scopes = {@OAuthScope(name = "openid", description = "OpenId登录"),@OAuthScope(name = "profile", description = "获取用户信息"),@OAuthScope(name = "message.read", description = "读"),@OAuthScope(name = "message.write", description = "写")}))
)})
public class SpringDocAnnoConfig {
}

yml中的配置

custom:info:title: example-apiversion: 0.0.1description: 这是一个使用SpringDoc生成的在线文档.terms-of-service: http://127.0.0.1:8080/example/test01license:name: Apache 2.0security:name: Authenticatetoken-url: http://kwqqr48rgo.cdhttp.cn/oauth2/tokenauthorization-url: http://kwqqr48rgo.cdhttp.cn/oauth2/authorize

注意：要想请求时携带登录获取的access_token，@OpenAPIDefinition注解中必须指定security属性，并且name值要和@SecurityScheme注解中的name属性一致。

还有一件事，@SecuritySchemes注解可以直接替换为@SecurityScheme注解，只指定一种认证方式。

还有一件事，使用注解的方式可以直接从yml中获取yml配置文件中的值，当然也可以直接使用具体的常量值(e.g. @License注解中的url属性)。

还有一件事，如果该配置类上只有@OpenAPIDefinition或 @SecurityScheme注解，并且该配置类中没有任何实现，则该配置类会在本机编译时消失，请添加@Configuration注解避免这种情况。
官网原文：If you give @OpenAPIDefinition or @SecurityScheme to a class that has no implementation, that class will disappear when you natively compile. To avoid this, give the class a @Configuration.

还有一件事…

Java代码配置

这里的注意事项和上边注解配置是一样的，不过由注解转为了Java类。

配置方式如下代码所示，详细内容请看代码中的注释

package com.example.config;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.info.License;
import io.swagger.v3.oas.models.security.OAuthFlow;
import io.swagger.v3.oas.models.security.OAuthFlows;
import io.swagger.v3.oas.models.security.Scopes;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** Spring Doc OpenApi Java代码配置** @author vains*/
@Configuration
public class SpringDocBeanConfig {@Beanpublic OpenAPI customOpenAPI() {// 基础信息Info info = new Info().title("example-api-java").version("0.0.1").description("这是一个使用SpringDoc生成的在线文档.").termsOfService("http://127.0.0.1:8080/example/test01").license(new License().name("Apache 2.0").url("http://127.0.0.1:8080/example/test01"));// 组件Components components = new Components();// 安全认证组件SecurityScheme securityScheme = new SecurityScheme();// 创建一个oauth认证流程OAuthFlows oAuthFlows = new OAuthFlows();// 设置OAuth2流程中认证服务的基本信息OAuthFlow oAuthFlow = new OAuthFlow()// 授权申请地址.authorizationUrl("http://kwqqr48rgo.cdhttp.cn/oauth2/authorize")// 获取token地址.tokenUrl("http://kwqqr48rgo.cdhttp.cn/oauth2/token").scopes(new Scopes().addString("openid", "OpenId登录").addString("profile", "获取用户信息").addString("message.read", "读").addString("message.write", "写"));// 使用授权码模式oAuthFlows.authorizationCode(oAuthFlow);// OAuth2流程securityScheme.flows(oAuthFlows).type(SecurityScheme.Type.OAUTH2);// 安全认证名String securityName = "Authenticate";// 将认证配置加入组件中components.addSecuritySchemes(securityName, securityScheme);SecurityRequirement securityRequirement = new SecurityRequirement();// 将安全认证和swagger-ui关联起来securityRequirement.addList(securityName);return new OpenAPI()// 基础描述信息.info(info)// 添加OAuth2认证流程组件.components(components)// 添加请求时携带OAuth2规范的请求头(通过OAuth2流程获取token后发请求时会自动携带Authorization请求头).addSecurityItem(securityRequirement);}}

效果预览

启动项目后打开提供的在线文档地址：

http://127.0.0.1:8080/swagger-ui/index.html

右侧多了一个Authorize按钮。
操作演示流程如下

其它基础配置

关于springdoc-openapi-core-properties和swagger-ui properties在官网中有详细的介绍了，就不展开说明了，读者可以对照文档在yml中添加自己的相关配置。

附录

1. SpringDoc官网
2. 代码仓库：Gitee、Github