api文档自动生成工具

安装教程

spring-boot集成：
1 添加依赖
- 添加依赖包

       
            com.gitee.sergius
            api-generator
            2.0.0
        

2 添加配置bean：

    @Bean
    public ApiComponent creatApiComponent(){
        return new ApiComponent()
                .addScanPackage("com.gitee.sergius.smarthome.intelligent.depot.restapi")
                .withYamlFilePath("D:/")
                .withParseDepth(3)
                .withServerHost("http://ip:host/")
                .build();
    }

• addScanPackage：添加api扫描包，可以一次添加多个包，例如 addScanPackage（“com.package1”,“com.package2”）
• withYamlFilePath:配置扫描完成后是否生成存储文件，该文件存储各个api信息，如果配置了该路径，当接口方法上面的方法tag变更之后，会保留之前的接口信息，这样做主要是为了可以做接口版本控制，如果不需要，可以不配置此项，此时如果修改了接口tag，之前的版本将不做保留。
• withParseDepth：请求参数和返回参数递归扫描的层数，主要用来防止当请求参数或者响应参数配置中如果有循环嵌套的时候出现死循环。
• withServerHost：此参数主要用来配置页面显示的接口请求路径的主机地址部分。

3 添加扫描的controller包：

  @ComponentScan("com.gitee.sergius.apitool.web")  

spring-mvc集成：
1 添加依赖
- 添加依赖包

            com.gitee.sergius
            api-generator
            2.0.0
        

2 添加配置bean：

   @Configuration
   @ComponentScan("com.gitee.sergius.apitool.web")
   public class ApiConfiguration {

        @Bean
        public ApiComponent apiComponent(){
            return new ApiComponent()
                .withScanPackage("com.sandalice.api.controller")
                .withServerHost("http://ip:host/")
                .withYamlFilePath("d:/")
                .withYamlFileName("doc.yaml")
                .build();
        }
    }

也可以在spring mvc的配置文件中通过配置项添加扫描controller。

3 添加servlet-mapping
为保证/api-doc接口请求url可以被分发，需要确认分发类DispatcherServlet能够处理/api-doc请求，该项通常在web.xml中配置，举例：

    
    sandalice
    org.springframework.web.servlet.DispatcherServlet
    
      contextConfigLocation
      
    
    1
  
  
    *.htm
    *.json
    *.jsp
    /api-doc
  

 如上配置项中的url-pattern

---

注解说明

1 @Api

     @Api(desc = "接口说明",contentType = MediaType.APPLICATION_FORM_URLENCODED,tag = "1.0")

- desc：接口说明
- contentType ：接口请求方式
- tag：接口标签

该注解可以用在类|方法上面，类上可以不添加，但是需要生成接口文档的方法上面必须添加，desc仅用在接口方法上时才有效，contentType和tag优先采用接口方法上的定义。

2 @ApiCustomerParams、@ApiCustomerParam 两个需要配合使用
多个入参时：

        @ApiCustomerParams({
            @ApiCustomerParam(name = "email", desc = "用户邮箱" ,required = false,dataType = DataType.STRING ,example = "[email protected]"),
            @ApiCustomerParam(name = "school", desc = "毕业院校" ,required = false,dataType = DataType.STRING , example = "中国大学"),
            @ApiCustomerParam(name = "name",desc = "用户名称",isArray = true, dataType = DataType.STRING),
            @ApiCustomerParam(name = "method",desc = "调用方法" ,required = false,dataType = DataType.STRING),
            @ApiCustomerParam(name = "user",desc = "用户系统信息",isArray = true,dataType = DataType.CLASS,clazz = com.gitee.sergius.apitool.req.ApiReq.class)
    })

单个入参时可简写：

    @ApiCustomerParam(name = "user",desc = "用户系统信息",isArray = true,dataType = DataType.CLASS,clazz = com.gitee.sergius.apitool.req.ApiReq.class)

- name：字段名称 
- desc：字段说明
- required：是否必填（默认为true）
- dataType：字段数据类型
- example：示例
- isArray: 是否是集合类型（默认为false）
- clazz：实体类型对应的类路径，只有当dataType=DataType.CLASS时才必填

该注解可以用在方法上面，当入参不能通过方法参数直接判断出来时使用。

3 @ApiParam

     @ApiParam(name = "userId" , desc = "用户Id",required = false,example = "1000")

- name：字段名称 
- desc：字段说明
- required：是否必填（默认为true）
- example：示例

该注解可以用在方法参数上面，当没有定义@ApiCustomerParams和@ApiCustomerParam时使用，用于当入参可以直接通过方法参数判断出来的时候使用。
4 @ApiResponses、@ApiResponse 两个需要配合使用
多个返回参数时

 @ApiResponses({
            @ApiResponse(name = "name",desc = "用户姓名",dataType = DataType.STRING ,example = "李四"),
            @ApiResponse(name = "id",desc = "用户ID",dataType = DataType.LONG ,example = "1000"),
            @ApiResponse(name = "user",desc = "基本信息" ,dataType = DataType.CLASS ,isArray = true,clazz =com.gitee.sergius.apitool.resp.ApiResp.class)
    })

单个返回参数时可简写：

 @ApiResponse(name = "user",desc = "基本信息" ,dataType = DataType.CLASS ,isArray = true,clazz =com.gitee.sergius.apitool.resp.ApiResp.class)

- name：字段名称 
- desc：字段说明
- required：是否必填（默认为true）
- dataType：字段数据类型
- example：示例
- isArray: 是否是集合类型（默认为false）
- clazz：实体类型对应的类路径，只有当dataType=DataType.CLASS时才必填

该注解可以用在方法上面，当出参不能通过方法返回类型直接判断出来时使用。

5 @ApiExceptions、@ApiException 两个需要配合使用
多个返回参数时

   @ApiExceptions({
            @ApiException(code = "200",desc = "请求成功"),
            @ApiException(code = "300",desc = "重定向失败"),
            @ApiException(code = "400",desc = "网络错误"),
            @ApiException(code = "500",desc = "socket错误")
    })

单个返回参数时可简写：

    @ApiException(code = "200",desc = "请求成功")

- code：响应码 
- desc：响应说明

该注释可以用在类|方法上面，优先采用方法上的定义。

6 @ApiModel

    @ApiModel

该注解用在类上面，不含属性，当入参或者出参为CLASS封装类型时，该注解用来定义对应的封装类。

7 @ApiModelProperty

    @ApiModelProperty(name = "id",desc = "用户主键" ,example = "1000")

- name：字段名称 
- desc：字段说明
- required：是否必填（默认为true）
- example：示例

该注解用在属性上，当入参或者出参为CLASS封装类型时，该注解用来定义对应的封装类的各个属性。

---

请求地址

http(s)/${host}/api-doc

---

注解配置表示例

可以参考：api-platform/api-web/src/main/java/com/gitee/sergius/apiweb/api/MyApi.java

---

生成API文档界面展示