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

Question

我有以下两个实体类。

第一类是 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;
    }
}

第二个类是 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;
    }
}

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

这是我在生成的 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

我找到了解决方案。结果证明是类加载问题。我有一个 ear我用来部署 war 的库图书馆。两者war和 ear包含 swagger-annotations 工件的副本。这导致加载的注释类与 ear 中打包的不同。 .

我通过修改我的 pom.xml 解决了这个问题war 的文件图书馆。我将 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