Swagger/OpenAPI 3.0 生成 - 带有来自接口的通用列表的端点未显示在文档中

Question

我正在尝试使用 Swagger/OpenAPI 3.0 为 Java EE 应用程序生成 API 文档/swagger 客户端，但文档中一直缺少一种方法。 我创建了一个示例项目来澄清我的问题：

新的，不太复杂的例子：

我得到了一个带有列表的接口作为我的 REST 端点的参数：

    package de.rockbunker.api;

    import javax.ws.rs.core.Response;
    import java.util.List;

    public interface Pong<T> {
        Response pongList(List<T> pongs);
    }

我将实现此服务并添加 swagger 注释：

    package de.rockbunker.api;

    import io.swagger.v3.oas.annotations.Operation;

    import javax.enterprise.context.ApplicationScoped;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.core.Response;
    import java.util.List;

    @ApplicationScoped
    @Path("")
    public class PingService implements Pong<String> {

        // Does not show up in documentation!?
        @POST
        @Path("pongList")
        @Operation(summary = "Pong List in Interface", tags = "Pong")
        @Override
        public Response pongList(List<String> pongs) {
            return Response.ok().build();
        }

    }

我尝试使用 maven 插件生成 openapi 文档（完整配置见下文）：

            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.1</version>

但是生成的文档仍然是空的，端点没有显示：

openapi: 3.0.1

更复杂的例子

我的休息端点实现了一个带有类型参数的接口。 我尝试了几种方式使用这个参数，导致了这个界面

public interface Pong<T> {
    Response pongList(List<T> pongs);

    Response pongArray(T[] pongs);

    Response justPong(T pong);

    Response pongNoTypeParameter(List<Integer> intPongs);
}

实现该接口的服务如下所示：

    package de.rockbunker.api;

    import io.swagger.v3.oas.annotations.Operation;
    import io.swagger.v3.oas.annotations.Parameter;
    import io.swagger.v3.oas.annotations.media.Schema;

    import javax.enterprise.context.ApplicationScoped;
    import javax.ws.rs.GET;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.core.Response;
    import java.util.List;

    @ApplicationScoped
    @Path("")
    public class PingService implements Pong<String>{

        // Works
        @GET
        @Path("ping")
        @Operation(summary = "Just ping", tags = "Ping")
        public Response ping() {
            return Response.ok("Ping").build();
        }

        // Does not show up
        @POST
        @Path("pongListInInterface")
        @Operation(summary = "Pong List in Interface", tags = "Pong")
        @Override
        public Response pongList(List<String> pongs) {
            return Response.ok().build();
        }

        // Works
        @POST
        @Path("pongArrayInInterface")
        @Operation(summary = "Pong Array in Interface", tags = "Pong")
        @Override
        public Response pongArray(String[] pongs) {
            return Response.ok().build();
        }

        // Works
        @GET
        @Path("pong")
        @Operation(summary = "Just pong", tags = "Pong")
        @Override
        public Response justPong(String pong) {
            return Response.ok().build();
        }

        // Works
        @GET
        @Path("intPong")
        @Operation(summary = "Just Integer pongs", tags = "Pong")
        @Override
        public Response pongNoTypeParameter(List<Integer> intPongs) {
            return Response.ok().build();
        }

        // Works
        @POST
        @Path("pongListNoInterface")
        @Operation(summary = "Pong List no Interface", tags = "Pong")
        public Response pongListNoInterface(List<String> pongs) {
            return Response.ok().build();
        }
    }

使用 2.1.1 版本中的 Maven 插件 io.swagger.core.v3.swagger-annotations 生成 openapi 文档，生成的文档包含每个方法，但Response pongList(List<T> pongs); 该类型参数的所有其他用法都以某种方式很好地工作，只有当我使用该类型参数作为列表的类型时，我才能让它显示出来。

openapi: 3.0.1
paths:
  /pong:
    get:
      tags:
      - Pong
      summary: Just pong
      operationId: justPong
      requestBody:
        content:
          '*/*':
            schema:
              type: string
      responses:
        default:
          description: default response
          content:
            '*/*': {}
  /pongArrayInInterface:
    post:
      tags:
      - Pong
      summary: Pong Array in Interface
      operationId: pongArray
      requestBody:
        content:
          '*/*':
            schema:
              type: array
              items:
                type: string
      responses:
        default:
          description: default response
          content:
            '*/*': {}
  /ping:
    get:
      tags:
      - Ping
      summary: Just ping
      operationId: ping
      responses:
        default:
          description: default response
          content:
            '*/*': {}
  /intPong:
    get:
      tags:
      - Pong
      summary: Just Integer pongs
      operationId: pongNoTypeParameter
      requestBody:
        content:
          '*/*':
            schema:
              type: array
              items:
                type: integer
                format: int32
      responses:
        default:
          description: default response
          content:
            '*/*': {}
  /pongListNoInterface:
    post:
      tags:
      - Pong
      summary: Pong List no Interface
      operationId: pongListNoInterface
      requestBody:
        content:
          '*/*':
            schema:
              type: array
              items:
                type: string
      responses:
        default:
          description: default response
          content:
            '*/*': {}

插件配置：

<plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.1</version>
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputPath>${project.build.directory}/${project.artifactId}-${project.version}</outputPath>
                <outputFormat>JSONANDYAML</outputFormat>
                <resourcePackages>
                    <package>de.rockbunker.api</package>
                </resourcePackages>
                <prettyPrint>true</prettyPrint>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

完整的 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>de.rock-bunker</groupId>
    <artifactId>swagger-ui-test</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <dependencies>
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>8.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-client</artifactId>
            <version>4.3.1.Final</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.jboss.resteasy/resteasy-jackson2-provider -->
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jackson2-provider</artifactId>
            <version>4.3.1.Final</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-jaxrs2 -->
<!--        <dependency>-->
<!--            <groupId>io.swagger.core.v3</groupId>-->
<!--            <artifactId>swagger-jaxrs2</artifactId>-->
<!--            <version>2.1.1</version>-->
<!--        </dependency>-->
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>2.1.1</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.2.3</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>com.googlecode.maven-download-plugin</groupId>
                <artifactId>download-maven-plugin</artifactId>
                <version>1.2.1</version>
                <executions>
                    <execution>
                        <id>swagger-ui</id>
                        <goals>
                            <goal>wget</goal>
                        </goals>
                        <configuration>
                            <url>https://github.com/swagger-api/swagger-ui/archive/master.tar.gz</url>
                            <unpack>true</unpack>
                            <outputDirectory>${project.build.directory}</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>2.6</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>validate</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>target/${project.artifactId}-${project.version}</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>${project.build.directory}/swagger-ui-master/dist</directory>

                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.1</version>
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputPath>${project.build.directory}/${project.artifactId}-${project.version}</outputPath>
                <outputFormat>JSONANDYAML</outputFormat>
                <resourcePackages>
                    <package>de.rockbunker.api</package>
                </resourcePackages>
                <prettyPrint>true</prettyPrint>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

        </plugins>
    </build>
</project>

我不太明白。 为什么方法Response pongList(List<T> pongs); 文档中缺少？ 也许你可以告诉我:-)。

你好！

Answer 1

这对我来说就像一个错误。 作为一种解决方法，您可以将列表包装到另一个对象中，而无需任何类型参数，它应该可以工作。

你好

Answer 2

你也必须添加 Swagger-ui

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>