自定義swagger maven codegen插件

項目中需要根據openapi 2.0接口定義自動生成指定框架代碼，github中有對應的案例，不過生成的代碼框架不符合當前需求，因此根據項目需要自定義了一個codegen插件，這里記錄下插件流程

swagger-codegen項目github地址：https://github.com/swagger-api/swagger-codegen

maven插件編寫過程

1、IDEA創建maven-plugin工程

2、指定packaging和artifactId

maven插件packageing類型為maven-plugin，artifactId即為maven插件的命名，按照官方規范，maven插件命名建議為：xxxx-maven-plugin，這樣命名有兩個好處：

（1）maven-xxxx-plugin為maven官方插件命名，使用這種命名方式可能侵權

（2）自定義插件maven執行命令為mvn groupId:artifactId:goal，使用推薦命名方式，maven命令可以簡化為mvn xxxx:goal

3、繼承AbstactMojo自定義Mojo類

（1）@Mojo注解用來指定插件goalPrefix和執行的生命周期

（2）@Parameter注解用來指定該插件輸入參數

（3）execute()方法用來編寫maven插件邏輯

4、maven工程依賴及注意事項

（1）基礎依賴

<dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-plugin-api</artifactId>
    <version>3.6.0</version>
</dependency>
<dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-project</artifactId>
    <version>2.2.1</version>
</dependency>
<dependency>
    <groupId>org.apache.maven.plugin-tools</groupId>
    <artifactId>maven-plugin-annotations</artifactId>
    <version>3.6.0</version>
</dependency> <!--  Mojo類注解需要添加的依賴 -->

（2）注意事項：如果插件Mojo類中使用的java8語法，需要在build標簽中添加maven-plugin-plugin編譯依賴，並且顯式指定版本號為3.5.2及以上

swagger-codegen流程

1、添加swagger依賴

<dependency>
    <groupId>io.swagger.parser.v3</groupId>
    <artifactId>swagger-parser</artifactId>
    <version>2.0.20</version>
</dependency>
<dependency>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen</artifactId>
    <version>3.0.21</version>
</dependency>

2、定義mustache模板

swagger提供了解析mustache模板文件的方法，通過解析yaml文件定義及mustache模板，生成指定的java類；

mustache傳送門：https://github.com/mustache/mustache.github.com

舉例：生成api接口類mustache模板

package {{apiPackage}};

{{#importPackageList}}
import {{className}};{{/importPackageList}}
import javax.servlet.ServletException;

public interface {{className}}Api {
{{#pathGetEntity}}
    {{pathGetEntity.responseType}} {{pathGetEntity.methodName}}({{#pathGetEntity.params}}{{paramType}} {{paramName}}{{/pathGetEntity.params}}) throws ServletException;
{{/pathGetEntity}}{{#pathDeleteEntity}}
    void {{pathDeleteEntity.methodName}}({{#pathDeleteEntity.params}}{{paramType}} {{paramName}}{{/pathDeleteEntity.params}}) throws ServletException;
{{/pathDeleteEntity}}{{#pathPostEntity}}
    void {{pathPostEntity.methodName}}({{#pathPostEntity.params}}{{paramType}} {{paramName}}{{/pathPostEntity.params}}) throws ServletException;
{{/pathPostEntity}}{{#pathPutEntity}}
    void {{pathPutEntity.methodName}}({{#pathPutEntity.params}}{{paramType}} {{paramName}}{{/pathPutEntity.params}}) throws ServletException;
{{/pathPutEntity}}
}

3、通過開源swagger解析yaml定義

private Swagger createSwagger() throws MojoExecutionException {
    String apiFileStr;
    try {
        File file = new File(this.inputSpec);
        apiFileStr = FileUtils.readFileToString(file, StandardCharsets.UTF_8).trim();
    } catch (IOException e) {
        throw new MojoExecutionException("Read api file to string exception!");
    }

    return new SwaggerParser().parse(apiFileStr);
}

該swagger對象是基於openapi 2.0規范的解析對象，包含paths、definations等

4、根據輸入解析及mustache模板，生成對應的api接口類

private void writeToFile(Object context, String fileName, String templateName) {
    try {
        // 獲取模板信息
        String templateFileString = this.getTempFileString(templateName);

        // 生成模板
        Template template = Mustache.compiler().compile(templateFileString);

        // 解析模板
        String executeResult = template.execute(context);

        // 生成java類
        String outputPath = this.getOutputFilePath(fileName, templateName);
        FileUtils.writeStringToFile(new File(outputPath), executeResult, StandardCharsets.UTF_8, true);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

5、yaml定義及生成的api接口類

swagger: "2.0"
info:
  title: Title
  description: Title
  version: 1.0.0
host: www
schemes:
  - https
basePath: /rest
paths:
  /test/v1/user:
    post:
      tags:
        - "MyUser"
      summary: "創建用戶"
      operationId: "createUser"
      produces:
        - "application/json"
      consumes:
        - "application/json"
      parameters:
        - name: "user"
          in: body
          description: "創建用戶"
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: "創建用戶成功."
    put:
      tags:
        - "MyUser"
      summary: "修改用戶"
      operationId: "modifyUser"
      produces:
        - "application/json"
      consumes:
        - "application/json"
      parameters:
        - name: "user"
          in: body
          description: "修改用戶"
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: "修改用戶成功."
  /test/v1/user/{id}:
    delete:
      tags:
        - "MyUser"
      summary: "通過ID刪除用戶"
      operationId: "deleteUserById"
      produces:
        - "application/json"
      consumes:
        - "application/json"
      parameters:
        - name: "id"
          in: query
          description: "通過ID刪除用戶"
          required: true
          type: "integer"
          format: "int64"
      responses:
        200:
          description: "Delete family members by person id"
    get:
      tags:
        - "MyUser"
      summary: "通過ID獲取用戶信息"
      operationId: "getUserById"
      produces:
        - "application/json"
      consumes:
        - "application/json"
      parameters:
        - name: "id"
          in: query
          description: "通過ID獲取用戶信息"
          required: true
          type: "integer"
          format: "int64"
      responses:
        200:
          description: "Retrieves family members by person id"
          schema:
            $ref: '#/definitions/User'
definitions:
  User:
    type: "object"
    required:
      - "id"
      - "firstName"
      - "lastName"
      - "dateOfBirth"
      - "gender"
    properties:
      id:
        type: "integer"
        format: "int64"
      firstName:
        type: "string"
        example: "John"
      lastName:
        type: "string"
        example: "Smith"
      dateOfBirth:
        type: "string"
        example: "1992-10-05"

package com.demo.api;

import com.demo.model.User;
import javax.servlet.ServletException;

public interface MyUserApi {
    User getUserById(Integer id) throws ServletException;

    void deleteUserById(Integer id) throws ServletException;

    void createUser(User user) throws ServletException;

    void modifyUser(User user) throws ServletException;
}

本文只是簡單記錄下通過swagger編寫maven插件的過程，完整的代碼見我的github

swagger-codegen插件地址：https://github.com/bale1992/swagger-codegen-maven-plugin

測試工程地址：https://github.com/bale1992/swagger-codegen-maven-plugin-test