Generazione della documentazione dell'interfaccia utente di Swagger per l'API REST

Question

Ho la mia API REST sviluppata utilizzando JAX-RS/Jersey in Java. Voglio convertire/generare la documentazione UI basata su Swagger per questo. Qualcuno può dirmi preciso/passaggi in modo semplice su come farlo? Mi dispiace, ma i passi dati sul loro sito sono poco vaghi per me.

Answer 1

Ci sono diversi modi per integrare spavalderia-core con l'applicazione, ma in base alla descrizione, avevo appena seguire la pagina wiki come descritto sia da https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 o https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5 a seconda della versione di Jersey si utilizza.

Queste pagine si collegano anche a una serie di campioni che è possibile utilizzare come riferimento e vedere come funzionano. Inoltre inseriscono swagger-ui direttamente in essi in modo da poter vedere un'intera serie di interazioni.

Answer 2

Swagger ha una buona documentazione di implementazione passo per passo su github.

Si dovrebbero usare annotazioni swagger su metodi, risorse, modelli. Quindi devi configure your web.xml as described here. Dopo tutti questi passaggi, è possibile raggiungere swagger-ui yourdomain/api-docs o un altro percorso configurato nel percorso di ascolto di web.xml ApiDeclarationServlet.

C'è un sample swagger app Jax-rs/Jersey

Swagger UI è una collezione senza la dipendenza di HTML, Javascript, CSS e le attività che generano dinamicamente bella documentazione e sandbox da un API Swagger-compliant. Poiché l'interfaccia utente di Swagger non ha dipendenze, è possibile ospitarla in qualsiasi ambiente server o sul computer locale.

• C'è una bella discussione per cominciare statica dipendenza. Normalmente è necessario copiare e incollare le statistiche di swagger-ui. https://github.com/swagger-api/swagger-ui/issues/758
• distribuzione Swagger UI https://github.com/swagger-api/swagger-ui/tree/master/dist
• Un altro esempio di app che utilizza spavalderia: https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
• riferimento semplice su swagger implementation with springboot (che non è necessario web.xml in questa situazione).

Answer 3

È necessario utilizzare roaster: è possibile apportare modifiche al codice sorgente per aggiungere nuove annotazioni. Ecco un esempio per illustrare come usarlo nel tuo caso:

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

    } 
} 

Ed ecco l'output:

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

Il modo più semplice che conosco è quello di utilizzare il plugin Maven jaxrs Analyzer. Il che può essere trovato su 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> 

Questo crea l'JSON spavalderia per voi con mvn install clean. Per quanto ne so, non ha bisogno di alcuna manipolazione del web.xml ecc. Come avviene tramite l'analisi bytecode.

Fonte: Adam Bien weblog entry & il suo demo in una delle sessione airhacks

Bonus: a nove minuti video dal creatore del plugin che spiega l'utilizzo