gpt4 book ai didi

java - Swagger/OpenAPI 3.0 代 - 具有来自接口(interface)的通用列表的端点未显示在文档中

转载 作者:行者123 更新时间:2023-12-04 04:17:54 24 4
gpt4 key购买 nike

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

新的、不太复杂的例子:

我得到一个带有列表的接口(interface)作为我的 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

更复杂的例子

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

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

Response pongArray(T[] pongs);

Response justPong(T pong);

Response pongNoTypeParameter(List<Integer> intPongs);
}

实现接口(interface)的服务如下所示:


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);文档中缺少?也许你可以告诉我:-)。

您好!

最佳答案

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

问候

关于java - Swagger/OpenAPI 3.0 代 - 具有来自接口(interface)的通用列表的端点未显示在文档中,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/60188417/

24 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com