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}",
                // license
                license = @License(
                        name = "${custom.license.name}",
                        // license 地址
                        url = "http://127.0.0.1:8080/example/test01"
                )
        ),
        // 这里的名字是引用下边 @SecurityScheme 注解中指定的名字，指定后发起请求时会在请求头中按照OAuth2的规范添加token
        security = @SecurityRequirement(name = "${custom.security.name}")
)
@SecuritySchemes({@SecurityScheme(
        // 指定 SecurityScheme 的名称(OpenAPIDefinition注解中的security属性中会引用该名称)
        name = "${custom.security.name}",
        // 指定认证类型为oauth2
        type = 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 {
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

yml中的配置

custom:
  info:
    title: example-api
    version: 0.0.1
    description: 这是一个使用SpringDoc生成的在线文档.
    terms-of-service: http://127.0.0.1:8080/example/test01
  license:
    name: Apache 2.0
  security:
    name: Authenticate
    token-url: http://kwqqr48rgo.cdhttp.cn/oauth2/token
    authorization-url: http://kwqqr48rgo.cdhttp.cn/oauth2/authorize
 
1
2
3
4
5
6
7
8
9
10
11
12
13

注意：要想请求时携带登录获取的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 {

    @Bean
    public 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);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

效果预览

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

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

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

其它基础配置

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

附录

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