webentwicklung-frage-antwort-db.com.de

Generieren von Swagger-UI-Dokumentation für REST API

Ich habe meine REST API mit JAX-RS/Jersey in Java entwickelt. Ich möchte eine Swagger-basierte UI-Dokumentation dafür konvertieren/generieren. Kann mir jemand auf einfache Weise genaue/Schritte mitteilen? Es tut mir leid, aber die auf ihrer Website angegebenen Schritte sind für mich etwas vage.

26
user3767923

Es gibt verschiedene Möglichkeiten, um swagger-core in Ihre Anwendung zu integrieren, aber basierend auf Ihrer Beschreibung würde ich einfach der Wiki-Seite folgen, die entweder von https://github.com/swagger-api/swagger-core) beschrieben wird /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 verwendeten Jersey-Version.

Diese Seiten enthalten auch Links zu einer 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 Reihe von Interaktionen sehen können.

6
Ron

Der einfachste Weg, den ich kenne, ist die Verwendung des JAXRS Analyzer-Maven-Plugins. Welches kann auf GitHub gefunden werden

<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 den Swagger Json für Sie mit MVN Clean Install. Nach meinem besten Wissen ist keine Manipulation der Datei web.xml usw. erforderlich, da dies über die Bytecode-Analyse erfolgt.

Quelle: Adam Bien Weblog Eintrag & seine Demo in einer der Airhacks-Sitzungen

Bonus: 9 Minuten Video vom Ersteller des Plugins, der die Verwendung erklärt

6
dubes

Swagger hat schrittweise Implementierungen von Nice-Dokumentation auf Github.

Sie sollten Swagger-Annotationen für Ihre Methoden, Ressourcen und Modelle verwenden. Dann sollten Sie konfigurieren Sie Ihre web.xml wie hier beschrieben . Nach all diesen Schritten können Sie swagger-ui yourdomain/api-docs oder einen anderen Pfad erreichen, der im Abhörpfad von web.xml ApiDeclarationServlet konfiguriert wurde.

Es gibt eine Beispiel Swagger App Jax-Rs/Jersey

Swagger UI ist eine abhängigkeitsfreie Sammlung von HTML-, Javascript- und CSS-Assets, die aus einer Swagger-kompatiblen API dynamisch eine ansprechende Dokumentation und eine Sandbox generieren. Da die Swagger-Benutzeroberfläche keine Abhängigkeiten aufweist, können Sie sie in jeder Serverumgebung oder auf Ihrem lokalen Computer hosten.

1
İlker Korkut

Verwenden Sie Röster : Sie können den Quellcode ändern, um neue Anmerkungen hinzuzufügen. Hier ist ein Beispiel, um zu veranschaulichen, wie es in Ihrem Fall verwendet wird:

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; 
}
1
Master Mind