# 使用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、将原来的springfox相关的依赖删除。
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认证   
  ![](https://support.huaweicloud.com/devg-astropro/zh-cn_image_0000002157723057.png "点击放大")
  在未输入认证凭证时，直接访问需要认证的接口会返回需要认证的信息：
  图2返回认证信息   
  ![](https://support.huaweicloud.com/devg-astropro/zh-cn_image_0000002122364334.png "点击放大")
  输入认证凭证：
  图3输入认证凭证   
  ![](https://support.huaweicloud.com/devg-astropro/zh-cn_image_0000002130355962.png "点击放大")
  图4认证完成   
  ![](https://support.huaweicloud.com/devg-astropro/zh-cn_image_0000002157771585.png "点击放大")
  输入认证凭证后，再次调用接口时会将认证信息以配置的方式同请求内容一同发送。
  图5发送认证信息   
  ![](https://support.huaweicloud.com/devg-astropro/zh-cn_image_0000002130515258.png "点击放大")