安裝教程

spring-boot整合： 1. 新增依賴 - 新增依賴包

       <dependency>
            <groupId>com.gitee.sergius</groupId>
            <artifactId>api-generator</artifactId>
            <version>2.0.0</version>
        </dependency>

1. 新增配置bean：

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

   • addScanPackage：新增api掃描包，可以一次新增多個包，例如 addScanPackage（”com.package1”,”com.package2”）
   • withYamlFilePath:配置掃描完成後是否生成儲存檔案，該檔案儲存各個api資訊，如果配置了該路徑，當介面方法上面的方法tag變更之後，會保留之前的介面資訊，這樣做主要是為了可以做介面版本控制，如果不需要，可以不配置此項，此時如果修改了介面tag，之前的版本將不做保留。
   • withParseDepth：請求引數和返回引數遞迴掃描的層數，主要用來防止當請求引數或者響應引數配置中如果有迴圈巢狀的時候出現死迴圈。
   • withServerHost：此引數主要用來配置頁面顯示的介面請求路徑的主機地址部分。
   • 新增掃描的controller包：

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

spring-mvc整合： 1. 新增依賴 - 新增依賴包

<dependency>
            <groupId>com.gitee.sergius</groupId>
            <artifactId>api-generator</artifactId>
            <version>2.0.0</version>
        </dependency>

1. 新增配置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://haiershequ.com:7531/IntelligentCommunity")
               .withYamlFilePath("d:/")
               .withYamlFileName("doc.yaml")
               .build();
       }
   }

   也可以在spring mvc的配置檔案中通過配置項新增掃描controller。

2. 新增servlet-mapping 為保證/api-doc介面請求url可以被分發，需要確認分發類DispatcherServlet能夠處理/api-doc請求，該項通常在web.xml中配置，舉例：

    <servlet>
    <servlet-name>sandalice</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value></param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <url-pattern>*.htm</url-pattern>
    <url-pattern>*.json</url-pattern>
    <url-pattern>*.jsp</url-pattern>
    <url-pattern>/api-doc</url-pattern>
  </servlet-mapping>

 如上配置項中的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文件介面展示