java - example - Generación de documentación de Swagger UI para REST API

swagger tutorial español

Question

Tengo mi API REST desarrollada usando JAX-RS / Jersey en Java. Quiero convertir / generar la documentación de UI basada en Swagger para ello. ¿Alguien, por favor, puede decirme los pasos precisos de manera simple sobre cómo hacerlo? Lo siento, pero los pasos dados en su sitio son poco vagos para mí.

Answer 1

Debe usar el roaster : puede hacer la modificación del código fuente para agregar nuevas anotaciones. Aquí hay un ejemplo para ilustrar cómo usarlo en su 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);

    }
}

Y aquí está la salida:

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 2

Hay varias formas de integrar swagger-core con su aplicación, pero según su descripción, simplemente seguiría la página wiki como se describe en 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 dependiendo de La versión de Jersey que usas.

Esas páginas también se vinculan a un conjunto de muestras que puede usar como referencia y ver cómo funcionan. También incorporan swagger-ui directamente hacia ellos para que puedas ver un conjunto completo de interacción.

Answer 3

La forma más fácil que conozco es usar el complemento de análisis JAXRS Analyzer. Que se puede encontrar en 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>

Esto crea el swage json para ti con mvn clean install. Según mi conocimiento, no necesita ninguna manipulación del web.xml, etc., ya que lo hace a través del análisis de código de bytes.

Fuente: entry weblog de Adam Bien y su demostración en una de las sesiones de airhacks.

Bonificación: un video 9 minutos del creador del complemento que explica el uso.

Answer 4

Swagger tiene buena documentación, implementaciones paso a paso en github.

Debería usar anotaciones arrogantes en sus métodos, recursos, modelos. Entonces debes configurar tu web.xml como se describe aquí . Después de todos estos pasos, puede llegar a swagger-ui yourdomain / api-docs u otra ruta que haya configurado en la ruta de escucha de web.xml ApiDeclarationServlet.

Hay una aplicación de swagger de muestra Jax-rs / Jersey

Swagger UI es una colección libre de dependencias de HTML, Javascript y elementos CSS que generan dinámicamente una hermosa documentación y una caja de arena desde una API compatible con Swagger. Como la interfaz de usuario de Swagger no tiene dependencias, puede alojarla en cualquier entorno de servidor o en su máquina local.

• Hay una buena discusión sobre la dependencia de las estadísticas. Normalmente necesitas copiar y pegar estadísticas de swagger-ui. https://github.com/swagger-api/swagger-ui/issues/758
• Distribución de la interfaz de usuario Swagger https://github.com/swagger-api/swagger-ui/tree/master/dist
• Otra aplicación de ejemplo que utiliza swagger: https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
• Referencia simple sobre la implementación de Swagger con springboot (que no es necesario web.xml en esta situación).