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包含在招摇的注解神器副本。这导致加载的注释类与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