web-dev-qa-db-fra.com

Génération de la documentation de l'interface utilisateur Swagger pour REST

J'ai mon REST API développée en utilisant JAX-RS/Jersey en Java. Je veux convertir/générer la documentation de l'interface utilisateur basée sur Swagger pour cela. Quelqu'un peut-il me dire précisément/étapes de manière simple sur comment faire? Je suis désolé mais, les étapes indiquées sur leur site sont peu vagues pour moi.

javaswaggerswagger-ui
26
user3767923

Il existe plusieurs façons d'intégrer swagger-core à votre application, mais en fonction de votre description, je suivrais simplement la page wiki comme décrit soit par https://github.com/swagger-api/swagger-core /wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 ou https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey- 2.X-Project-Setup-1.5 selon la version de Jersey que vous utilisez.

Ces pages renvoient également à un ensemble d'échantillons que vous pouvez utiliser pour référence et voir comment ils fonctionnent. Ils attirent également swagger-ui directement en eux afin que vous puissiez voir un ensemble complet d'interactions.

6
Ron

La manière la plus simple que je connaisse est d'utiliser le plugin maven de JAXRS Analyzer. Qui peut être trouvé sur 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>

Cela crée le swagger json pour vous avec mvn clean install. À ma connaissance, il n'a besoin d'aucune manipulation du web.xml etc. car il le fait via une analyse de bytecode.

Source: weblog d'Adam Bien entrée & sa démo dans l'une des sessions airhacks

Bonus: 9 minutes vidéo par le créateur du plugin expliquant l'utilisation

6
dubes

Swagger a une implémentation étape par étape de la documentation Nice sur github.

Vous devez utiliser des annotations swagger sur vos méthodes, ressources, modèles. Ensuite, vous devez configurer votre web.xml comme décrit ici . Après toutes ces étapes, vous pouvez atteindre swagger-ui yourdomain/api-docs ou un autre chemin configuré dans le chemin d'écoute de web.xml ApiDeclarationServlet.

Il y a un exemple d'application swagger Jax-rs/Jersey

Swagger UI est une collection sans dépendance d'actifs HTML, Javascript et CSS qui génère dynamiquement une belle documentation et un bac à sable à partir d'une API compatible Swagger. L'interface utilisateur de Swagger n'ayant aucune dépendance, vous pouvez l'héberger dans n'importe quel environnement de serveur ou sur votre machine locale.

1
İlker Korkut

Vous devez utiliser roaster : vous pouvez faire une modification du code source pour ajouter de nouvelles annotations. Voici un exemple pour illustrer comment l'utiliser dans votre cas:

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

    }
}

Et voici la sortie:

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