Generieren Swagger UI-Dokumentation für REST-API

Question

Ich habe meine REST API mit JAX-RS/Jersey in Java entwickelt. Ich möchte die Swagger-basierte UI-Dokumentation dafür konvertieren/generieren. Kann mir bitte jemand genau sagen/Schritte auf einfache Art und Weise wie man das macht? Es tut mir leid, aber Schritte auf ihrer Website sind für mich wenig vage.

Answer 1

Es gibt mehr Möglichkeiten Prahlerei-Kern mit Ihrer Anwendung zu integrieren, sondern auf der Grundlage Ihrer Beschreibung, ich würde nur die Wiki-Seite folgen, wie entweder beschrieben durch https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 oder https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5 abhängig von der Jersey-Version verwenden.

Diese Seiten verweisen auch auf eine Reihe von Beispielen, die Sie als Referenz verwenden können, um zu sehen, wie sie funktionieren. Sie ziehen auch Swagger-Ui direkt in sie hinein, so dass Sie eine vollständige Interaktion sehen können.

Answer 2

Swagger hat nette Dokumentation Schritt für Schritt Implementierungen auf GitHub.

Sie sollten Swagger-Annotationen für Ihre Methoden, Ressourcen und Modelle verwenden. Dann sollten Sie configure your web.xml as described here. Nach all diesen Schritten können Sie swagger-ui yourdomain/api-docs oder einen anderen Pfad erreichen, der im Listening-Pfad von web.xml ApiDeclarationServlet konfiguriert wurde.

Es gibt eine sample swagger app Jax-rs/Jersey

Swagger UI ist eine Abhängigkeit freie Sammlung von HTML, Javascript und CSS-Assets, die dynamisch schöne Dokumentation und Sandkasten von einem Swagger-kompatiblen API generieren. Da die Swagger-Benutzeroberfläche keine Abhängigkeiten aufweist, können Sie sie in einer beliebigen Serverumgebung oder auf Ihrem lokalen Computer hosten.

• Es gibt eine nette Diskussion über Statik Abhängigkeit zu erhalten. Normalerweise müssen Sie Swagger-ui Statiken kopieren und einfügen. https://github.com/swagger-api/swagger-ui/issues/758
• Swagger UI Verteilung https://github.com/swagger-api/swagger-ui/tree/master/dist
• Ein weiteres Beispiel-App, die Prahlerei verwendet: https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
• Einfache Referenz über swagger implementation with springboot (nicht web.xml in dieser Situation benötigt wird).

Answer 3

Sie sollten roaster verwenden: Sie können Quellcodeänderungen vornehmen, um neue Anmerkungen hinzuzufügen. Hier ist ein Beispiel, wie es in Ihrem Fall zu verwenden:

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); 

    } 
} 

Und hier ist die Ausgabe:

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; 
} 

Answer 4

Der einfachste Weg, ich weiß, ist das JAXRS Analyzer Maven Plugin zu verwenden. Welche können auf 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> 

Dies schafft die Prahlerei json für Sie mit mvn saubere Installation zu finden. Soweit ich weiß, ist keine Manipulation der web.xml usw. notwendig, wie es bei der Bytecode-Analyse der Fall ist.

Quelle: Adam Bien Weblog entry & seine Demo in einer der airhacks Sitzung

Bonus: ein 9 Minuten video vom Schöpfer des Plugins Erläuterung der Nutzung