如何在swagger-maven-plugin 3.1.0中设置替代模型

Question

如何在swagger-maven-plugin 3.1.0和Swagger UI 2.0（或更新版本）中设置替代模型？

最近，我们将Swagger UI从1.2升级到了2.0，并将swagger-maven-plugin从2.3升级到了3.1.0。

似乎swagger-maven-plugin版本3.1.0缺少了2.3版本中存在的overridingModels选项。

该选项使我们能够自定义某些数据类型的架构描述，如https://github.com/swagger-api/swagger-core/wiki/overriding-models中所述 。

Answer 1

这是我最终解决问题的方式（我正在使用swagger-maven-plugin版本3.1.1）：

假设您要将java.util.Date映射为以下任意结构：

{
  "year": "string",
  "month": "string",
  "day": "string"
}

步骤1：创建一个描述上述模型的类：

package com.example;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel
public class MyDate {

    @ApiModelProperty
    public String year;

    @ApiModelProperty
    public String month;

    @ApiModelProperty
    public String day;
}

注意：类名和包名是任意的，它们只需要位于类路径上，因此该类对插件可见，就像模型的其余部分一样。

步骤2：在pom.xml将此行添加到swagger-maven-plugin的配置中：

<plugin>
  <groupId>com.github.kongchen</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <version>3.1.1</version>
  <configuration>
    <apiSources>
      <apiSource>
        ...
        <modelSubstitute>/model-substitute.csv</modelSubstitute>
      </apiSource>
    </apiSources>
  </configuration>
  ...
</plugin>

步骤3：使用以下映射创建文件model-substitute.csv ：

java.util.Date : com.example.MyDate

将该文件放在与插件相同的maven模块中，位于目录src/main/resources 。
注意：文件名是任意的，但应与pom.xml中的值匹配。