swagger
swagger-ui

Observaciones

swagger-ui con jersey REST WS

Como dice el sitio web oficial de Swagger :

Swagger es definir una interfaz estándar, independiente del idioma para las API REST, que permite que tanto los humanos como las computadoras descubran y comprendan las capacidades del servicio sin acceso al código fuente, la documentación o la inspección de tráfico de la red. Cuando se define correctamente a través de Swagger, un consumidor puede comprender e interactuar con el servicio remoto con una cantidad mínima de lógica de implementación. Al igual que las interfaces que han hecho para la programación de nivel inferior, Swagger elimina las conjeturas al llamar al servicio.

Suponiendo que use Maven y jersey, deberá agregar la siguiente dependencia: Maven Swagger Dependency junto con las dependencias de JAX-RS. Ahora tiene que crear "aplicación web maven" y debajo de la aplicación web necesita pegar los contenidos presentes en esta URL . La estructura de carpetas de la aplicación web debe tener el siguiente aspecto después de pegar esos contenidos en su proyecto:

Después de eso siga estos pasos:

1. Cree un archivo java con cualquier nombre (en nuestro caso es " ApiOriginFilter.java ") similar a continuación:

import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;

import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class ApiOriginFilter implements javax.servlet.Filter {
    /**
     * doFilter
     */
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletResponse res = (HttpServletResponse) response;
        res.addHeader("Access-Control-Allow-Origin", "*");
        res.addHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
        res.addHeader("Access-Control-Allow-Headers", "Content-Type, api_key, Authorization");
        chain.doFilter(request, response);
    }

    /**
     * destroy
     */
    @Override
    public void destroy() {
    }

    /**
     * init
     */
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
    }
}

Este archivo se asegurará de filtrar las solicitudes entrantes según lo dispuesto en la clase.

2. Cree un archivo java con cualquier nombre, supongamos que en nuestro caso su nombre es " SwaggerJaxrsConfig.java " como sigue:

import org.eclipse.persistence.jaxb.MarshallerProperties;
import org.eclipse.persistence.jaxb.BeanValidationMode;
import org.glassfish.jersey.moxy.json.MoxyJsonConfig;
import org.glassfish.jersey.moxy.json.MoxyJsonFeature;
import org.glassfish.jersey.moxy.xml.MoxyXmlFeature;
import org.glassfish.jersey.server.ResourceConfig;

import org.glassfish.jersey.server.ServerProperties;
import org.glassfish.jersey.server.filter.RolesAllowedDynamicFeature;
import io.swagger.jaxrs.config.BeanConfig;

public class SwaggerJaxrsConfig extends ResourceConfig {

public SwaggerJaxrsConfig() {
    BeanConfig beanConfig = new BeanConfig();
    beanConfig.setTitle("Swagger API Title");
    beanConfig.setVersion("1.0.0");        
    beanConfig.setSchemes(new String[] { "http" });
    beanConfig.setHost("localhost:8080/swagger-ui");
    beanConfig.setBasePath("/rest");
    beanConfig.setResourcePackage(
            "your.restws.package");
    beanConfig.setScan(true);        
    property(ServerProperties.BV_SEND_ERROR_IN_RESPONSE, Boolean.TRUE);
    packages("your.restws.package");
    packages("io.swagger.jaxrs.listing");
    register(MoxyJsonFeature.class);
    // register(BadRequestExceptionMapper.class);
    register(new MoxyJsonConfig().setFormattedOutput(true)
    // Turn off BV otherwise the entities on server would be validated by MOXy as well.
    .property(MarshallerProperties.BEAN_VALIDATION_MODE, BeanValidationMode.NONE).resolver());

    register(MoxyXmlFeature.class);
    register(RolesAllowedDynamicFeature.class);
}
}

Como puede ver, en la clase anterior, proporcionamos todos los detalles necesarios para usar la interfaz de usuario swagger como Host en el que se alojará este proyecto swagger junto con la función de establecer la ruta base de su elección y todos los protocolos http compatibles como " http " o " https " e incluso más detalles según su requerimiento. También hay una disposición para que Swagger conozca toda la ubicación de su REST WS que puede configurarse usando setResourcePackage junto con paquetes. Esta clase nos permite usar la interfaz de usuario de Swagger con nuestra personalización.

Ahora ingrese los 2 archivos anteriores en web.xml para usarlos después de implementar nuestra aplicación en el servidor, como a continuación:

<servlet>
    <servlet-name>jersey-servlet</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>your.package.SwaggerJaxrsConfig</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>jersey-servlet</servlet-name>
    <url-pattern>/rest/*</url-pattern>
</servlet-mapping>

<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>your.package.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/rest/*</url-pattern>
</filter-mapping>

Ahora, nos moveremos al código real donde usaremos las anotaciones provistas por Swagger:

Cree un Employee.java de frijoles como se muestra a continuación:

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("Employee bean")
public class Employee {

    private String name;
    private String id;
    private String dept;

    @ApiModelProperty(value = "Name of employee", example = "Test Employee")
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @ApiModelProperty(value = "Id of employee", example = "123456")
    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    @ApiModelProperty(value = "Department of employee", example = "IT Division", allowableValues = "IT, Sales, Admin")
    public String getDept() {
        return dept;
    }

    public void setDept(String dept) {
        this.dept = dept;
    }
}

Los componentes de Swagger que usamos aquí son:

1. @ApiModel("Employee bean") : esto decidirá el nombre de la clase Bean que se debe mostrar en la interfaz de usuario de Swagger.
2. @ApiModelProperty(value ="ABC", example="DeptName") - Esto proporcionará información de cada campo utilizado en el bean. el valor proporciona una descripción del campo y el ejemplo proporciona un valor de muestra de ese campo.

Ahora crearemos un Controlador REST de la siguiente manera para crear un servicio web GET de la siguiente manera:

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.GenericEntity;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.swagger.ws.bean.Employee;
import org.swagger.ws.service.EmployeeService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@Path("/employee")
@Api(tags = {"Employee"})
public class EmployeeController {
    private static final Logger LOGGER = LoggerFactory.getLogger(EmployeeController.class);

@GET
@Produces(MediaType.APPLICATION_JSON + ";charset=utf-8")
@ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class)
@ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@ApiResponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 500, message = "Internal Server Error", response = Error.class) })
public Response getEmployee()  {
        EmployeeService employeeService = new EmployeeService();
        Employee empDetails = employeeService.getEmployee();
        Response response;
        LOGGER.debug("Fetching employee");
        GenericEntity<Employee> entity = new GenericEntity<Employee>(empDetails){}; 
        response = Response.status(200).entity(entity).build();
        return response;
    }
}

Los componentes de Swagger que usamos aquí son:

1. @Api(tags = {"Employee"}) : esta anotación le dirá a Swagger cuál debe ser el título del servicio web. En este caso el título es " Employee ". Tenga en cuenta que algunos estándares al escribir REST WS también son aplicables al escribir Documentación Swagger como el título no debería ser como " GetEmployee " o " DeleteEmployee ", etc.
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) : esta anotación proporciona una breve idea acerca de su servicio web.
   • produces describe el formato de respuesta,
   • value describe breve idea sobre el servicio web
   • notes describen información detallada sobre este servicio web en caso de que existan.
3. @ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@ApiResponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 500, message = "Internal Server Error", response = Error.class) }) - Estas anotaciones nos proporcionan una forma de maneja diferentes tipos de códigos de estado HTTP que pueden recibirse como respuesta mientras consumes este servicio web. Nos permite establecer el código de error, el mensaje personalizado en su contra e incluso nos permite detectar ese error en una clase de error separada, si es necesario.

Finalmente, tenemos que crear una clase de servicio real que obtenga los detalles de los empleados cuando el servicio web sea consumido por el cliente. Puede implementarlo según sea necesario. A continuación se muestra el servicio de muestra para el propósito de demostración:

public class EmployeeService {

public Employee getEmployee() {
    Employee employee = new Employee();
    employee.setId("1");
    employee.setName("Test");
    employee.setDept("IT");
    return employee;
    }
}

Ahora está listo para ver su documentación en la interfaz de usuario de Swagger. Despliegue su proyecto Swagger e inicie el servidor. Ahora ve al navegador y presiona la URL de tu proyecto. En este caso su

http: // localhost: 8080 / swagger-ui /

Si swagger está correctamente configurado, debería poder ver la siguiente pantalla:

Ahora, para ver la documentación de su servicio web, proporcione la "base_url / rest / swagger.json" de su proyecto en el cuadro de texto ( http://exampl.com/api) que puede ver en la imagen de arriba. Después de proporcionar esa URL en el cuadro de texto, puede ver la siguiente pantalla con la documentación de su servicio web REST:

El cuadro de texto donde se escribe la " api key " en la imagen de arriba, puede proporcionar un encabezado específico o un valor clave si su proyecto lo exige como autenticación basada en la identificación del usuario, etc. Para eso, también deberá realizar cambios en index.html bajo la etiqueta que comienza con <input placeholder="api_key" ......

Otro beneficio adicional de Swagger-UI es que proporciona un botón "¡ Try it out! ". Este botón le permite habilitar para ver cuál podría ser la respuesta de este servicio web. Para este caso, si hacemos clic en ese botón, daremos la siguiente respuesta en la pantalla:

Así que esta es la demostración de muestra para Swagger UI. Hay muchas opciones que aún puede descubrir mientras escribe el controlador REST que lo ayudará a nivel de documentación al usar más anotaciones y sus atributos.