java - documentar api rest con swagger

Generar documentación de Rest API utilizando swagger o cualquier otra herramienta

Question

Estoy buscando una forma de documentar mis API de descanso. Mi servidor es un servidor Tomcat / Spring y las API Rest se implementan usando Jenkins.

Swagger parece ser una solución muy buena, pero no puedo entender cómo puedo usarla con mi código. Estoy buscando la mejor manera de crear el json swagger -ui puede leer- ¿cómo debería hacer eso?

Además, me gustaría comprobar cualquier otra buena solución para documentar las API de reposo en dicho entorno.

Answer 1

Para habilitar swagger-ui, puede usarlo "tal cual", a partir de la documentación:

"¡Puedes usar el código swagger-ui TAL CUAL! No hay necesidad de compilar o recompilar: solo clona este repositorio y utiliza los archivos preconstruidos en la carpeta dist. Si te gusta swagger-ui as-is, detente aquí. "

Así que, básicamente, solo necesitaría colocar los contenidos "dist" en su servidor web, luego debe ingresar el punto final swagger de su servicio web en la interfaz de usuario, por ejemplo: http://localhost:8080/Webservice/api-doc.json (este es el mismo punto final de dirección que debe definir en su web.xml).

Sospecho que tiene otros detalles mal configurados, lo cual es fácil, ya que hay varios lugares donde tiene que configurar Swagger. A continuación, le doy algunos detalles de mi propia configuración en Swagger.

Este es un fragmento de las configuraciones de Swagger en mi web.xml:

<!-- // Jersey declaration -->
<servlet>
    <servlet-name>web service</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.config.property.classnames</param-name>
        <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value>
    </init-param>
    <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/Webservice</param-value>
    </init-param>
    <init-param>
        <param-name>api.version</param-name>
        <param-value>0.0.2</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
    <servlet-name>Bootstrap</servlet-name>
    <servlet-class>com.mywebservice.utils.swagger.Bootstrap</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>com.mywebservice.utils.swagger.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Bellow es una lista del paquete com.mywebservice.utils.swagger , donde hay varios recursos, tal como se presentan en la documentación de Swagger (que ahora parece ser diferente de cuando lo configuré, así que aquí está la lista completa de documentos) :

Puede encontrar estos archivos (o ejemplos) en el proyecto de ejemplo de Swagger: https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs , que debe intentar usar como una "plantilla". "para configurar tu arrogancia. El único archivo con el que tuve problemas fue el ApiListingResource:

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.jaxrs.JavaApiListing;

@Path("/resources.json")
@Api("/resources")
@Produces({ "application/json"})
public class ApiListingResource extends JavaApiListing{
}

HTH.

Answer 2

Si está usando JAX-RS y maven, también puede probar MireDot , es súper fácil de configurar.

Answer 3

No he intentado arrodillarme, pero puedes intentar enunciar . Puede generar documentación de los puntos finales JAX-RS como parte de la fase javadoc. Algunos ejemplos de documentación generada están disponibles en la página de enunciado

Actualizar

El proyecto se ha movido a http://enunciate.webcohesion.com/ , java 8 será compatible con la próxima versión 2.0.