Swagger 不扫描位于不同 jar 文件中的实体类中的 ApiModel 和 ApiModelProperty 注释

Question

我有以下两个实体 classes.

第一个class是SampleApiEntity:

package my.company.rest;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.hibernate.annotations.Type;
import java.io.Serializable;
import java.sql.Timestamp;
import java.util.UUID;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;

@ApiModel (
    value       = "SampleApiEntity",
    description = "This is a sample entity from the Api package."
)
@Entity
public class SampleApiEntity
        implements Serializable
{
    public SampleApiEntity () {}

    private static final long serialVersionUID = 1L;

    @Column (nullable = false)
    @ApiModelProperty (
        value    = "level",
        required = true
    )
    private Integer   level;

    @Column (length = 255)
    @ApiModelProperty (
        value    = "description"
    )
    private String    description;

    @Column (nullable = false)
    @ApiModelProperty (
        value    = "time",
        required = true
    )
    private Timestamp time;

    @Id
    @Column (
        unique   = true,
        nullable = false
    )
    @Type (type = "pg-uuid")
    @ApiModelProperty (
        value    = "id",
        readOnly = true,
        dataType = "uuid",
        example  = "123e4567-e89b-12d3-a456-426655440000"
    )
    private UUID      sampleApiEntityId;

    public String getDescription ()
    {
        return this.description;
    }

    public Integer getLevel ()
    {
        return this.level;
    }

    public UUID getSampleApiEntityId ()
    {
        return this.sampleApiEntityId;
    }

    public Timestamp getTime ()
    {
        return this.time;
    }

    public void setDescription (String description)
    {
        this.description = description;
    }

    public void setLevel (Integer level)
    {
        this.level = level;
    }

    public void setSampleApiEntityId (UUID sampleApiEntityId)
    {
        this.sampleApiEntityId = sampleApiEntityId;
    }

    public void setTime (Timestamp time)
    {
        this.time = time;
    }
}

第二个class是SampleModelEntity:

package my.company.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.hibernate.annotations.Type;
import java.io.Serializable;
import java.sql.Timestamp;
import java.util.UUID;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;

@ApiModel (
    value       = "SampleModelEntity",
    description = "This is a sample entity from the Model package."
)
@Entity
public class SampleModelEntity
        implements Serializable
{
    public SampleModelEntity () {}

    private static final long serialVersionUID = 1L;

    @Column (nullable = false)
    @ApiModelProperty (
        value    = "level",
        required = true
    )
    private Integer   level;

    @Column (length = 255)
    @ApiModelProperty (
        value    = "description"
    )
    private String    description;

    @Column (nullable = false)
    @ApiModelProperty (
        value    = "time",
        required = true
    )
    private Timestamp time;

    @Id
    @Column (
        unique   = true,
        nullable = false
    )
    @Type (type = "pg-uuid")
    @ApiModelProperty (
        value    = "id",
        readOnly = true,
        example  = "123e4567-e89b-12d3-a456-426655440000"
    )
    private UUID      sampleModelEntityId;

    public String getDescription ()
    {
        return this.description;
    }

    public Integer getLevel ()
    {
        return this.level;
    }

    public UUID getSampleModelEntityId ()
    {
        return this.sampleModelEntityId;
    }

    public Timestamp getTime ()
    {
        return this.time;
    }

    public void setDescription (String description)
    {
        this.description = description;
    }

    public void setLevel (Integer level)
    {
        this.level = level;
    }

    public void setSampleModelEntityId (UUID sampleModelEntityId)
    {
        this.sampleModelEntityId = sampleModelEntityId;
    }

    public void setTime (Timestamp time)
    {
        this.time = time;
    }
}

两个 classes 之间的唯一区别是它们是在单独的 JAR 文件中定义的。 SampleApiEntity 与 REST 资源 class 打包在同一个 JAR 中。 SampleModelEntity 与其他实体 classes 打包在单独的 JAR 中。生成的 swagger.yaml 文件同时包含 class，但缺少 ApiModel 和 ApiModelProperty 注释为 SampleModelEntity class 提供的信息。

这是我在生成的 swagger.yaml 文件中看到的内容：

SampleApiEntity:
  type: "object"
  required:
  - "level"
  - "time"
  properties:
    level:
      type: "integer"
      format: "int32"
      description: "level"
    description:
      type: "string"
      description: "description"
    time:
      type: "string"
      format: "date-time"
      description: "time"
    sampleApiEntityId:
      type: "string"
      format: "uuid"
      example: "123e4567-e89b-12d3-a456-426655440000"
      description: "id"
      readOnly: true
  description: "This is a sample entity from the Api package."
SampleModelEntity:
  type: "object"
  properties:
    level:
      type: "integer"
      format: "int32"
    description:
      type: "string"
    time:
      type: "string"
      format: "date-time"
    sampleModelEntityId:
      type: "string"
      format: "uuid"

谁能帮我理解为什么 ApiModel 和 ApiModelProperty 注释没有在 swagger.yaml 中生成输出？

Answer 1

我找到了解决方案。结果是 class 加载问题。我有一个 ear 库，用于部署 war 库。 war 和 ear 都包含 swagger-annotations 工件的副本。这导致加载的注释 classes 与 ear.

中打包的注释不同

我通过为 war 库修改我的 pom.xml 文件解决了这个问题。我将 swagger-annotations 添加为显式依赖项，并将其范围设置为 provided:

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.10</version>
        <scope>provided</scope>
    </dependency>

您可以在此处找到更多信息：https://github.com/swagger-api/swagger-core/issues/2582

Answer 2

如果您有一个多模块 maven 项目并使用 maven swagger 插件，一个小提示。这个星座也会出现同样的问题

|-Module1 ( Rest paths )
 |--> pom.xml
|-Module2 ( Models )
 |--> pom.xml
|--> pom.xml ( Parent pom )

将插件添加到父 pom 并从这里启动。

这可以防止 class 加载问题，并且注释将被 swagger "scanner" 以正确的方式识别和处理 "scanner"。

Swagger 不扫描位于不同 jar 文件中的实体 类 中的 ApiModel 和 ApiModelProperty 注释

Swagger not scanning ApiModel and ApiModelProperty annotations in entity classes that are in a different jar file

java

rest

entity

swagger

Swagger 不扫描位于不同 jar 文件中的实体类中的 ApiModel 和 ApiModelProperty 注释