为 REST API 生成 Swagger UI 文档
Generating Swagger UI documentation for REST API
我使用 Java 中的 JAX-RS/Jersey 开发了我的 REST API。我想为其转换基于 to/generate Swagger 的 UI 文档。谁能用简单的方式告诉我 precise/steps 如何做到这一点?很抱歉,他们网站上给出的步骤对我来说有点模糊。
Swagger 在 github.
上有很好的文档分步实施
您应该在您的方法、资源和模型上使用 swagger 注释。那你应该configure your web.xml as described here。完成所有这些步骤后,您可以到达 swagger-ui yourdomain/api-docs 或在 web.xml ApiDeclarationServlet 的监听路径中配置的其他路径。
有个sample swagger app Jax-rs/Jersey
Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API. Because Swagger UI has no dependencies, you can host it in any server environment, or on your local machine.
- 有一个关于获取静态依赖的很好的讨论。通常您需要复制并粘贴 swagger-ui statics。
https://github.com/swagger-api/swagger-ui/issues/758
- Swagger UI 分布
https://github.com/swagger-api/swagger-ui/tree/master/dist
- 另一个使用 swagger 的示例应用程序:
https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
- 关于swagger implementation with springboot的简单参考(在这种情况下不需要web.xml)。
有多种方法可以将 swagger-core 与您的应用程序集成,但根据您的描述,我会按照 https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 or https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5 描述的维基页面,具体取决于您使用的 Jersey 版本。
这些页面还 link 了一组示例,您可以将其用作参考并了解它们的工作原理。他们还将 swagger-ui 直接拉入其中,以便您可以看到完整的交互集。
您应该使用 roaster :您可以修改源代码以添加新注释。
下面是一个示例来说明如何在您的案例中使用它:
package ma.cars.iscraper;
import org.jboss.forge.roaster.Roaster;
import org.jboss.forge.roaster.model.source.*;
import java.util.List;
public class Main {
public static void main(String[] args) {
String originalClassSourceCode = "@Path(\"user\")\n public class SomeClass { @GET\n" +
" @Path(\"{userId}\")\n public Response getUserById() {\n return null; \n}";
System.out.println("Before : \n" + originalClassSourceCode);
JavaClassSource javaClass =
Roaster.parse(JavaClassSource.class,originalClassSourceCode );
String pathValue = null;
// extract Path annotation value
List<AnnotationSource<JavaClassSource>> listAnnotations = javaClass.getAnnotations();
for (AnnotationSource annotation :listAnnotations) {
if (annotation.getName().equals("Path")) {
pathValue = annotation.getStringValue();
}
}
AnnotationSource<JavaClassSource> apiAnnotation = javaClass.addAnnotation("com.wordnik.swagger.annotations.Api");
apiAnnotation.setLiteralValue("\"" + pathValue + "\"") ;
List<MethodSource<JavaClassSource>> methods = javaClass.getMethods();
for (MethodSource<JavaClassSource> method: methods) {
for (AnnotationSource annotation: method.getAnnotations()) {
if (annotation.getName().equals("DELETE") || annotation.getName().equals("GET")
|| annotation.getName().equals("POST") || annotation.getName().equals("PUT")) {
String returnTypeClass = method.getReturnType().getQualifiedName();
AnnotationSource<JavaClassSource> apiOperation = method.addAnnotation("com.wordnik.swagger.annotations.ApiOperation");
apiOperation.setLiteralValue("value", "\"value\"");
apiOperation.setLiteralValue("response", "\"" + returnTypeClass + ".class\"");
}
}
}
System.out.println(javaClass);
}
}
这是输出:
Before :
@Path("user")
public class SomeClass { @GET
@Path("{userId}")
public Response getUserById() {
return null;
}
After :
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;@Path("user")
@Api("user")
public class SomeClass { @GET
@Path("{userId}")
@ApiOperation(value = "value", response = "Response.class")
public Response getUserById() {
return null;
}
我知道的最简单的方法是使用 JAXRS Analyzer maven 插件。可以在 GitHub
上找到
<plugin>
<groupId>com.sebastian-daschner</groupId>
<artifactId>jaxrs-analyzer-maven-plugin</artifactId>
<version>0.4</version>
<executions>
<execution>
<goals>
<goal>analyze-jaxrs</goal>
</goals>
<configuration>
<!-- Available backends are plaintext (default), swagger and asciidoc -->
<backend>plaintext</backend>
<!-- Domain of the deployed project, defaults to example.com -->
<deployedDomain>example.com</deployedDomain>
</configuration>
</execution>
</executions>
这为您使用 mvn clean install 创建了 swagger json。据我所知,它不需要对 web.xml 等进行任何操作,因为它是通过字节码分析来完成的。
来源:Adam Bien 博客 entry 和他在其中一个 airhack 中的演示 session
奖励:插件创建者解释用法的 9 分钟 video
我使用 Java 中的 JAX-RS/Jersey 开发了我的 REST API。我想为其转换基于 to/generate Swagger 的 UI 文档。谁能用简单的方式告诉我 precise/steps 如何做到这一点?很抱歉,他们网站上给出的步骤对我来说有点模糊。
Swagger 在 github.
上有很好的文档分步实施您应该在您的方法、资源和模型上使用 swagger 注释。那你应该configure your web.xml as described here。完成所有这些步骤后,您可以到达 swagger-ui yourdomain/api-docs 或在 web.xml ApiDeclarationServlet 的监听路径中配置的其他路径。
有个sample swagger app Jax-rs/Jersey
Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API. Because Swagger UI has no dependencies, you can host it in any server environment, or on your local machine.
- 有一个关于获取静态依赖的很好的讨论。通常您需要复制并粘贴 swagger-ui statics。 https://github.com/swagger-api/swagger-ui/issues/758
- Swagger UI 分布 https://github.com/swagger-api/swagger-ui/tree/master/dist
- 另一个使用 swagger 的示例应用程序: https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
- 关于swagger implementation with springboot的简单参考(在这种情况下不需要web.xml)。
有多种方法可以将 swagger-core 与您的应用程序集成,但根据您的描述,我会按照 https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 or https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5 描述的维基页面,具体取决于您使用的 Jersey 版本。
这些页面还 link 了一组示例,您可以将其用作参考并了解它们的工作原理。他们还将 swagger-ui 直接拉入其中,以便您可以看到完整的交互集。
您应该使用 roaster :您可以修改源代码以添加新注释。 下面是一个示例来说明如何在您的案例中使用它:
package ma.cars.iscraper;
import org.jboss.forge.roaster.Roaster;
import org.jboss.forge.roaster.model.source.*;
import java.util.List;
public class Main {
public static void main(String[] args) {
String originalClassSourceCode = "@Path(\"user\")\n public class SomeClass { @GET\n" +
" @Path(\"{userId}\")\n public Response getUserById() {\n return null; \n}";
System.out.println("Before : \n" + originalClassSourceCode);
JavaClassSource javaClass =
Roaster.parse(JavaClassSource.class,originalClassSourceCode );
String pathValue = null;
// extract Path annotation value
List<AnnotationSource<JavaClassSource>> listAnnotations = javaClass.getAnnotations();
for (AnnotationSource annotation :listAnnotations) {
if (annotation.getName().equals("Path")) {
pathValue = annotation.getStringValue();
}
}
AnnotationSource<JavaClassSource> apiAnnotation = javaClass.addAnnotation("com.wordnik.swagger.annotations.Api");
apiAnnotation.setLiteralValue("\"" + pathValue + "\"") ;
List<MethodSource<JavaClassSource>> methods = javaClass.getMethods();
for (MethodSource<JavaClassSource> method: methods) {
for (AnnotationSource annotation: method.getAnnotations()) {
if (annotation.getName().equals("DELETE") || annotation.getName().equals("GET")
|| annotation.getName().equals("POST") || annotation.getName().equals("PUT")) {
String returnTypeClass = method.getReturnType().getQualifiedName();
AnnotationSource<JavaClassSource> apiOperation = method.addAnnotation("com.wordnik.swagger.annotations.ApiOperation");
apiOperation.setLiteralValue("value", "\"value\"");
apiOperation.setLiteralValue("response", "\"" + returnTypeClass + ".class\"");
}
}
}
System.out.println(javaClass);
}
}
这是输出:
Before :
@Path("user")
public class SomeClass { @GET
@Path("{userId}")
public Response getUserById() {
return null;
}
After :
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;@Path("user")
@Api("user")
public class SomeClass { @GET
@Path("{userId}")
@ApiOperation(value = "value", response = "Response.class")
public Response getUserById() {
return null;
}
我知道的最简单的方法是使用 JAXRS Analyzer maven 插件。可以在 GitHub
上找到<plugin>
<groupId>com.sebastian-daschner</groupId>
<artifactId>jaxrs-analyzer-maven-plugin</artifactId>
<version>0.4</version>
<executions>
<execution>
<goals>
<goal>analyze-jaxrs</goal>
</goals>
<configuration>
<!-- Available backends are plaintext (default), swagger and asciidoc -->
<backend>plaintext</backend>
<!-- Domain of the deployed project, defaults to example.com -->
<deployedDomain>example.com</deployedDomain>
</configuration>
</execution>
</executions>
这为您使用 mvn clean install 创建了 swagger json。据我所知,它不需要对 web.xml 等进行任何操作,因为它是通过字节码分析来完成的。
来源:Adam Bien 博客 entry 和他在其中一个 airhack 中的演示 session
奖励:插件创建者解释用法的 9 分钟 video