2015-05-23 1 views
23

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.Generieren Swagger UI-Dokumentation für REST-API

+0

ich konnte nicht wirklich, wo ich wollte mit Swagger zu kommen; Ich benutzte Jodocs: https://github.com/mashery/iodocs. Schauen Sie, was Sie für eine Alternative halten. – Rots

+0

Überprüfen Sie [this] (http://jakubstas.com/spring-jersey-swagger-create-documentation/) Tutorial, es gibt Schritt für Schritt Anweisungen zum Generieren von UI-Dokumentation für Ihre API. –

+0

Swagger ist eine Spezifikation. Haben Sie bereits entschieden, welche Implementierung von Swagger Sie verwenden werden? Wenn ja, was ist das? Wenn nein, möchtest du prolong-springmvc verwenden? – DolphinJava

Antwort

6

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.

+0

nicht hilfreich. nichts auf der Benutzeroberfläche dort – Rentonie

+0

Die Frage wurde bearbeitet * nach * dieser Antwort. Die Antwort ist für die ursprüngliche Frage in Ordnung, da sie nichts direkt mit der Benutzeroberfläche hatte. – Ron

+1

Beachten Sie, dass nur Klassen mit '@ Api'-Annotation von swagger gescannt werden. –

1

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.

+0

Es tut mir leid, aber der Link zum Konfigurieren der web.xml ist einfach falsch und nicht relevant für die Konfiguration in der Frage. – Ron

+0

Es gibt eine Beispiel-App jax-rs/Trikot auch es hat web.xml Datei konfiguriert, BTW ich habe es nicht versucht. –

1

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

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

+0

Wie konfiguriere ich das auf Eclipse? –

+0

Wenn Sie ein Maven-Projekt haben, müssen Sie nur die Abhängigkeit hinzufügen und die Finsternis übernehmen. Ohne Maven muss ich prüfen, wie es benutzt werden kann. – dubes

+0

Ich habe die Abhängigkeit hinzugefügt..aber ich sehe diesen Fehler. Plugin com.test.webservices: jaxrs-analyzer-maven-plugin: 0.4 oder eine seiner Abhängigkeiten konnten nicht aufgelöst werden: Fehler beim Finden von com.test.webservices: jaxrs-analyzer-maven-plugin: jar: 0.4 in http://repo.maven.apache.org/maven2 wurde im lokalen Repository zwischengespeichert, die Auflösung wird nicht wiederholt, bis das Aktualisierungsintervall von central abgelaufen ist oder Updates erzwungen werden. –

Verwandte Themen