Java Swagger/OpenAPI 3.0生成-文档中未显示具有接口通用列表的端点
我试图使用swagger/OpenAPI 3.0为javaee应用程序生成API文档/swagger客户端,但文档中始终缺少一种方法。 我创建了一个示例项目来澄清我的问题: 新的、不太复杂的示例: 我得到了一个接口,其中一个列表作为我的REST端点的参数:Java Swagger/OpenAPI 3.0生成-文档中未显示具有接口通用列表的端点,java,swagger,resteasy,openapi,swagger-maven-plugin,Java,Swagger,Resteasy,Openapi,Swagger Maven Plugin,我试图使用swagger/OpenAPI 3.0为javaee应用程序生成API文档/swagger客户端,但文档中始终缺少一种方法。 我创建了一个示例项目来澄清我的问题: 新的、不太复杂的示例: 我得到了一个接口,其中一个列表作为我的REST端点的参数: package de.rockbunker.api; import javax.ws.rs.core.Response; import java.util.List; public interface Po
package de.rockbunker.api;
import javax.ws.rs.core.Response;
import java.util.List;
public interface Pong<T> {
Response pongList(List<T> pongs);
}
更复杂的示例
我的rest端点实现了一个带有类型参数的接口。我试着以几种方式使用这个参数,结果得到了这个接口
public interface Pong<T> {
Response pongList(List<T> pongs);
Response pongArray(T[] pongs);
Response justPong(T pong);
Response pongNoTypeParameter(List<Integer> intPongs);
}
插件配置:
<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>
io.swagger.core.v3
大摇大摆的maven插件
2.1.1
openapi
${project.build.directory}/${project.artifactId}-${project.version}
杰索南迪亚姆
de.rockbunker.api
真的
编译
决定
完整的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>
4.0.0
岩石掩体
招摇过市用户界面测试
1.0-快照
战争
爪哇
JavaEEAPI
8
假如
org.jboss.resteasy
resteasy客户端
4.3.1.最终版本
org.jboss.resteasy
resteasy-jackson2-provider
4.3.1.最终版本
io.swagger.core.v3
招摇过市的注解
2.1.1
org.apache.maven.plugins
maven战争插件
3.2.3
org.apache.maven.plugins
maven编译器插件
11
11
com.googlecode.maven-download-plugin
下载maven插件
1.2.1
大摇大摆的用户界面
wget
https://github.com/swagger-api/swagger-ui/archive/master.tar.gz
真的
${project.build.directory}
maven资源插件
2.6
复制资源
验证
复制资源
target/${project.artifactId}-${project.version}
${project.build.directory}/swagger ui master/dist
io.swagger.core.v3
大摇大摆的maven插件
2.1.1
openapi
${project.build.directory}/${project.artifactId}-${project.version}
杰索南迪亚姆
de.rockbunker.api
真的
编译
决定
我不太明白。为什么方法响应pongList(列出pong)文档中缺少代码>吗?也许你可以告诉我:-)
你好 您还必须添加招摇过市的用户界面
<!-- 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>
伊奥·斯普林福克斯
springfox招摇过市用户界面
2.9.2
我觉得这是一个bug。作为一种解决方法,您可以将列表包装到另一个对象中,而不使用任何类型参数
问候语我能为这篇文章添加什么吗?我觉得这没什么特别的,它应该可以工作。没有改变任何东西:(。它通常可以工作,只有通用列表的示例不能工作。它必须与配置有关,然后猜出什么问题了吗?这几乎是他们网站上的默认配置。我接受了!谢谢!
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();
}
}
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>
<?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>
<!-- 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>