Question

我在Java中使用JAX-RS / Jersey开发了我的REST API。我想为它转换为/生成基于Swagger的UI文档。任何人都可以告诉我精确/步骤简单的方法如何这样做？对不起，但他们网站上给出的步骤对我来说并不含糊。

Answer 1

有几种方法可以将swagger-core与您的应用程序集成，但根据您的描述，我只需按照https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5或https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5所述的Wiki页面，具体取决于Jersey版本你用。

这些页面还链接到一组样本，您可以将其用作参考，并了解它们的工作原理。他们还将swagger-ui直接插入其中，以便您可以看到一整套互动。

Answer 2

我知道最简单的方法是使用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＆amp;他在其中一个airhacks会议中的演示

奖励：插件的创建者解释使用情况的9分钟video

Answer 3

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是一个HTML，Javascript和CSS资产的无依赖项集合，可以从符合Swagger的API动态生成漂亮的文档和沙箱。由于Swagger UI没有依赖关系，因此您可以在任何服务器环境或本地计算机上托管它。

关于获得静态依赖性的讨论很好。通常你需要复制和粘贴swagger-ui静态。 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）。

Answer 4

您应该使用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; 
}

生成REST API的Swagger UI文档

4 个答案: