swagger2使用指南

引入依赖

通过Maven引入需要的依赖。

<dependency>
      <groupId>com.huaweicloud.devspore</groupId>
      <artifactId>swagger-extension-springfox</artifactId>
      <version>${devspore-swagger-extension.version}</version> #版本号，版本号可参考AstroPro-SDK版本变更与下载。
</dependency>

添加配置

com.huaweicloud.devspore:swagger-extension-springfox组件提供了如下配置项：

其中，devspore.swagger-extension.package-name为必填项，否则用此swagger文档生成的客户端代码编译将会有问题。

添加自定义注解

若有需要为方法添加一些自定义的特定注解，devspore-swagger-extension组件也提供了扩展机制，定义了如下接口：

import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.mvc.method.RequestMappingInfo;

import java.util.List;

public interface MethodAnnotationHandler {

    List<Annotation> getAnnotations(HandlerMethod handlerMethod, RequestMappingInfo requestMappingInfo);
}

关键类：
@Data
public class Annotation {
    /**
     * 最终生成注解名字，eg:  @SuppressWarnings("deprecation")
     */
    private String name;

    /**
     * 注解需要的import，eg: lombok.NonNull; （注意：每个import必须添加末尾的英文分号）
     */
    private List<String> imports;
}

使用者需实现此接口，并将对应实现类注入到spring的上下文里，如下为默认实现：

@Bean
@ConditionalOnMissingBean(MethodAnnotationHandler.class)
public MethodAnnotationHandler methodAnnotationHandler() {
	return ((handlerMethod, requestMappingInfo) -> new ArrayList<>());
}

获取swagger描述文档

启动项目后，访问http://{domain-url}/v2/api-docs，获取swagger描述文档。

泛型类处理示例

原有泛型类：

public class Result <T>{
    private T data;
    private String code;
    private String status;}

springfox默认生成的泛型类swagger描述：

 Result«string»:
    type: object
    properties:
      code:
        type: string
      data:
        type: string
      status:
        type: string
    title: Result«string»

使用此组件后生成的泛型类swagger描述：

在不破坏原有swagger的前提下，添加如下自定义swagger标签。

• x-generic：表示类的泛型参数。
• x-generic-class：表示泛型类名称。
• x-type：表示类成员的泛型类型。

 Result«string»:
    type: object
    properties:
      code:
        type: string
      data:
        type: string
        x-type: T
      status:
        type: string
    title: Result«string»
    x-generic-class: Result
    x-generic: T

以上自定义标签仅在使用AstroPro平台以swagger方式生成代码时使用。