# 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组件提供了如下配置项：
表1配置参数说明 
| 配置项                                             | 类型                   | 默认值    | 说明                                 |
|:---|:---|:---|:---|
| devspore.swagger-extension.springfox.enable     | Boolean              | true   | 是否对springfox-swagger进行扩展增强。        |
| devspore.swagger-extension.package-name         | String               | 无      | 使用此swagger生成代码时期望的package。         |
| devspore.swagger-extension.generate-mode        | Enum(CLIENT, SERVER) | CLIENT | 使用此swagger生成客户端代码或服务端代码。           |
| devspore.swagger-extension.client-model-package | String               | model  | 使用此swagger生成客户端代码时实体类的包名，默认为model。 |
| devspore.swagger-extension.additional-pom-gav   | List\<String\>       | 无      | 使用此swagger生成代码时需要添加的pom依赖。         |
   
其中，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方式生成代码时使用。