使用swagger进行在线API文档配置

文档配置

spring-boot-starter-huawei添加了swagger2和swagger3包的依赖，API在线文档使用springdoc-openapi-ui。springdoc基本配置较为简单，如下所示：

springdoc:
  api-docs:
    enabled: true
    path: /api-docs
    resolve-schema-properties: true
  swagger-ui:
    path: /swagger-ui.html #在线文档访问路径,实际访问路径为:http://{host}:{port}/{context-path}/swagger-ui.html
    showCommonExtensions: true
    disable-swagger-default-url: false

若原有项目中使用的是springfox+swagger，则启动时可能报错：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'swaggerWelcome' defined in class path resource [org/springdoc/webmvc/ui/SwaggerConfig.class]: Post-processing of merged bean definition failed; nested exception is java.lang.IllegalStateException: Failed to introspect Class [org.springdoc.webmvc.ui.SwaggerWelcomeWebMvc] from ClassLoader [sun.misc.Launcher$AppClassLoader@18b4aac2]

此时，若后续仍想使用springfox+swagger，则将spring-boot-starter-huawei中的springdoc排除即可:

<dependency>
    <groupId>com.huaweicloud</groupId>
    <artifactId>spring-boot-starter-huawei</artifactId>
    <version>${spring.boot.starter.huawei}</version>
    <exclusions>
        <exclusion>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
        </exclusion>
    </exclusions>
</dependency>

若后续使用springdoc生成在线api文档，则：

1、将原来的sprignfox相关的依赖删除。

2、将配置"SwaggerConfig"（根据实际情况查找配置类名称）相关的配置删除。

3、配置文件中添加springdoc的配置并删除springfox的配置。

swagger支持https和认证的方式

支持https

在启动类中加入注解：

@OpenAPIDefinition(
        servers = {
            @Server(
                    url = "https://coralgeneratorsvr.{Environment}-szv-kunpeng-camp.tools.huawei.com/coralgeneratorsvr", #替换成自己的服务地址
                    variables = {
                        @ServerVariable(
                                name = "Environment",# 参数定义,可使用{param}取其中的值
                                allowableValues = {"alpha", "beta", "gamma", "prod"},#参数取值范围
                                defaultValue = "alpha"),
                    },
                    description = "CoralGeneratorSvr Environmental Urls"),
            @Server(url = "http://localhost:8080/coralgeneratorsvr", description = "Local Dev Url")
        },
        info = # 服务描述信息
                @Info(
                        title = "CoralGeneratorSvr",
                        version = "v1",
                        description = "Coral Generator Server",
                        contact = @Contact(name = "x00464738", email = "xiaoweimin@huawei.com")))
@SpringBootApplication
@ComponentScan(value = {"com.huawei.coral", "com.huawei.coral.coralgeneratorsvr", "com.huawei.clouddragon.devuc.sdk.*", "com.huawei.clouddragon.apigateway_client"})
@MapperScan("com.huawei.coral.coralgeneratorsvr.mapper")
@Slf4j
public class Application extends SpringBootServletInitializer {
	...
}

支持服务接口认证

新增一个配置类，在配置类中加入以下配置：

/**
 * 在线文档接口认证配置
 *
 * @since 2021-08-12
 */
@Configuration(proxyBeanMethods = false)
public class SwaggerAuthConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("xAuthToken",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY) //请求认证类型
                                        .name("x-auth-token") //参数名称
                                        .description("sso proxy token: x-auth-token") //API key描述
                                        .in(SecurityScheme.In.HEADER))) //设置API key的存放位置（发送请求时请求头中会带上x-auth-token）
                .security(Collections.singletonList(new SecurityRequirement().addList("xAuthToken"))) //SecurityRequirement中配置的名称需要与SecuritySchema的名称匹配
                .info(new Info().title("AuthDemo")
                        .description("AuthDemo接口文档")
                        .version("0.2.0-RELEASE"));
    }
}

完成以上配置后，在线文档中会多出一个认证按钮：

图1 认证