swagger
swagger-ui

Remarques

swagger-ui avec le maillot REST WS

Comme le dit le site officiel de Swagger :

Swagger doit définir une interface standard, indépendante de la langue, pour les API REST, permettant aux humains et aux ordinateurs de découvrir et de comprendre les fonctionnalités du service sans accès au code source, à la documentation ou à l'inspection du trafic réseau. Lorsqu'il est correctement défini via Swagger, un consommateur peut comprendre et interagir avec le service distant avec une quantité minimale de logique d'implémentation. Semblable à ce que les interfaces ont fait pour la programmation de niveau inférieur, Swagger supprime les devinettes lors de l'appel du service.

En supposant que vous utilisiez Maven et maillot, vous devrez ajouter les dépendances suivantes: Maven Swagger Dependency avec les dépendances de JAX-RS. Maintenant, vous devez créer "maven webapp" et sous l'application Web, vous devez coller le contenu présent sur cette URL . La structure de dossier de webapp devrait ressembler à la suivante après avoir collé ces contenus dans votre projet:

Après cela, suivez ces étapes:

1. Créez un fichier java avec n'importe quel nom (dans notre cas, son " ApiOriginFilter.java ") similaire à ci-dessous:

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 {
    }
}

Ce fichier veillera à filtrer les demandes entrantes telles que fournies dans la classe.

2. Créez un fichier java de n'importe quel nom dans notre cas, son nom est " SwaggerJaxrsConfig.java " comme suit:

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

Comme vous pouvez le voir, dans la classe ci-dessus, nous avons fourni tous les détails nécessaires pour utiliser l'interface utilisateur swagger comme hôte sur lequel ce projet swagger sera hébergé avec possibilité de définir le chemin de base de votre choix et tous les protocoles http supportés comme " http " ou " https " et encore plus de détails selon vos besoins. Il est également prévu de permettre à Swagger de connaître l’emplacement de votre REST WS qui peut être défini avec setResourcePackage avec les paquets. Cette classe nous permet d’utiliser Swagger UI avec notre personnalisation.

Maintenant, saisissez au-dessus de 2 fichiers dans web.xml pour les utiliser après le déploiement de notre application sur le serveur, comme suit:

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

Maintenant, nous allons passer au code actuel où nous utiliserons les annotations fournies par Swagger:

Créez un bean Employee.java comme ci-dessous:

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

Les composants de Swagger utilisés ici sont:

1. @ApiModel("Employee bean") - @ApiModel("Employee bean") nom de la classe Bean à afficher sur l'interface utilisateur Swagger.
2. @ApiModelProperty(value ="ABC", example="DeptName") - @ApiModelProperty(value ="ABC", example="DeptName") des informations sur chaque champ utilisé dans le bean. value fournit une description du champ et l'exemple fournit la valeur de l'échantillon de ce champ.

Nous allons maintenant créer un contrôleur REST pour créer un service Web GET comme suit:

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

Les composants de Swagger utilisés ici sont:

1. @Api(tags = {"Employee"}) - Cette annotation indiquera à Swagger quel devrait être le titre du service Web. Dans ce cas, le titre est " Employee ". S'il vous plaît noter que quelques normes lors de l'écriture REST WS est également applicable lors de l'écriture de la documentation Swagger comme titre ne devrait pas être comme " GetEmployee " ou " DeleteEmployee ", etc.
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - Cette annotation fournit une brève idée à propos de votre webservice.
   • produces décrit le format de la réponse,
   • value décrit une brève idée du service Web
   • notes décrit des informations détaillées sur ce service Web en cas de besoin.
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) }) - Ces annotations nous permettent de gérer différents types de codes d'état HTTP pouvant être reçus en réponse à la consommation de ce service Web. Il nous permet de définir le code d'erreur, le message personnalisé et même de détecter cette erreur dans une classe d'erreurs séparée, si nécessaire.

Enfin, nous devons créer une classe de service réelle qui récupère les détails des employés lorsque le service Web est utilisé par le client. Vous pouvez le mettre en œuvre selon vos besoins. Voici l'exemple de service pour le but de la démo:

public class EmployeeService {

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

Vous êtes maintenant prêt à consulter votre documentation sur l'interface utilisateur Swagger. Déployez votre projet Swagger et démarrez le serveur. Maintenant, allez dans le navigateur et tapez l'URL de votre projet. Dans ce cas sa

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

Si swagger est correctement configuré, vous devriez pouvoir voir l'écran suivant:

Maintenant, pour voir la documentation de votre service Web, indiquez "base_url / rest / swagger.json" dans la zone de texte ( http://exampl.com/api) que vous pouvez voir dans l'image ci-dessus. Après avoir fourni cette URL dans la zone de texte, vous pouvez voir l'écran suivant fournissant la documentation de votre service Web REST:

La zone de texte où " api key " est écrite dans l'image ci-dessus, vous pouvez fournir une en-tête ou une valeur de clé spécifique si votre projet l'exige comme une authentification basée sur l'ID utilisateur, etc. Pour cela, vous devrez également modifier le fichier index.html sous la balise commençant par <input placeholder="api_key" ......

Un autre avantage supplémentaire de Swagger-UI est qu'il fournit un bouton " Try it out! ". Ce bouton vous permet de voir quelle pourrait être la réponse de ce service Web. Pour ce cas, si on clique sur ce bouton, il donnera la réponse suivante à l'écran:

Donc, ceci est la démo exemple pour Swagger UI. Il y a beaucoup d'options que vous pouvez encore découvrir en écrivant le contrôleur REST qui vous aidera au niveau de la documentation en utilisant plus d'annotations et leurs attributs.