自定义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