如何在 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 缺少 overridingModels 选项，它出现在 2.3 版中。

该选项使我们能够为某些数据类型自定义模式描述，如中所述：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 步：创建一个 class 描述上述模型：

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;
}

注意：class 名称和包名称是任意的，它们只需要在 class 路径上，所以 class 和其他插件一样可见你的模型。

第 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.

中的值匹配

Answer 2

NullPointerException 可能是因为您没有 src/main/resources 中的文件。这在 3.1.7 版本

中对我有用

如何在 swagger-maven-plugin 3.1.0 中设置覆盖模型

How to set overriding models in swagger-maven-plugin 3.1.0

maven

swagger

swagger-ui

swagger-maven-plugin

swagger-2.0