swagger
spavalderia-ui

Osservazioni

swagger-ui con maglia REST WS

Come dice il sito ufficiale di Swagger :

Swagger definisce un'interfaccia standard, indipendente dalla lingua, per le API REST, che consente a uomini e computer di scoprire e comprendere le funzionalità del servizio senza accesso a codice sorgente, documentazione o ispezione del traffico di rete. Se definito correttamente tramite Swagger, un utente può comprendere e interagire con il servizio remoto con una quantità minima di logica di implementazione. Simile a ciò che le interfacce hanno fatto per la programmazione di livello inferiore, Swagger rimuove le congetture nel chiamare il servizio.

Supponendo che tu usi Maven e jersey, dovrai aggiungere la seguente dipendenza: Maven Swagger Dipendenza insieme alle dipendenze di JAX-RS. Ora devi creare "maven webapp" e sotto la webapp devi incollare i contenuti presenti su questo URL . La struttura delle cartelle di webapp dovrebbe apparire come dopo aver incollato quei contenuti nel tuo progetto:

Quindi attenersi alla seguente procedura:

1. Creare un file java con qualsiasi nome (nel nostro caso è " ApiOriginFilter.java ") simile al seguente:

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

Questo file assicurerà di filtrare le richieste in arrivo come previsto nella classe.

2. Creare un file java di qualsiasi nome supponiamo nel nostro caso che il suo nome sia " SwaggerJaxrsConfig.java " come segue:

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

Come puoi vedere, nella suddetta classe abbiamo fornito tutti i dettagli necessari per utilizzare l'interfaccia utente swagger come Host su cui verrà ospitato questo swagger project insieme alla possibilità di impostare il percorso di base della tua scelta e tutti i protocolli http supportati come " http " o " https " e ancora più dettagli secondo le tue esigenze. setResourcePackage anche la possibilità di consentire a Swagger di conoscere tutta la posizione del tuo REST WS che può essere impostata usando setResourcePackage insieme ai pacchetti Questa classe ci consente di utilizzare l'interfaccia utente Swagger con la nostra personalizzazione.

Ora inserisci i 2 file sopra in web.xml in modo da utilizzarli dopo aver distribuito la nostra applicazione sul server come segue:

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

Ora passeremo al codice attuale in cui utilizzeremo le Annotazioni fornite da Swagger:

Creare un bean Employee.java come di seguito:

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

I componenti di Swagger che abbiamo usato qui sono:

1. @ApiModel("Employee bean") - Questo deciderà il nome della classe Bean che deve essere visualizzata nell'interfaccia utente di Swagger.
2. @ApiModelProperty(value ="ABC", example="DeptName") - Fornirà informazioni su ciascun campo utilizzato nel bean. valore fornisce una descrizione del campo e l'esempio fornisce il valore di esempio di quel campo.

Ora creeremo un controller REST come segue per creare un webservice GET come segue:

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

I componenti di Swagger che abbiamo usato qui sono:

1. @Api(tags = {"Employee"}) - Questa annotazione indicherà a Swagger quale dovrebbe essere il titolo del servizio web. In questo caso il titolo è " Employee ". Si noti che alcuni standard durante la scrittura di REST WS sono applicabili anche durante la scrittura di Swagger Documentation come il titolo non dovrebbe essere come " GetEmployee " o " DeleteEmployee ", ecc.
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - Questa annotazione fornisce una breve idea sul tuo webservice.
   • produces descrive il formato della risposta,
   • value descrive una breve idea sul webservice
   • notes descrive le informazioni dettagliate su questo servizio web in caso di qualsiasi.
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) }) - Queste annotazioni ci forniscono un modo per gestire diversi tipi di codici di stato HTTP che possono essere ricevuti come risposta mentre consumano questo servizio web. Ci consente di impostare il codice di errore, il messaggio personalizzato contro di esso e ci consente persino di rilevare l'errore nella classe di errore separata, se necessario.

Infine, dobbiamo creare una classe di servizio effettiva che recuperi i dettagli dei dipendenti quando il servizio web viene utilizzato dal client. Puoi implementarlo come richiesto. Di seguito è riportato il servizio di esempio per lo scopo Demo:

public class EmployeeService {

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

Ora sei pronto per vedere la tua documentazione nell'interfaccia utente di Swagger. Distribuisci il tuo progetto Swagger e avvia il server. Ora vai al browser e premi l'URL del tuo progetto. In questo caso è

http: // localhost: 8080 / spavalderia-ui /

Se swagger è configurato correttamente, dovresti essere in grado di vedere la seguente schermata:

Ora, per vedere la documentazione del tuo webservice fornire "base_url / rest / swagger.json" del tuo progetto nella casella di testo ( http://exampl.com/api) che puoi vedere nell'immagine qui sopra. Dopo aver fornito quell'URL nella casella di testo, puoi vedere la seguente schermata che fornisce la documentazione del tuo webservice REST:

La casella di testo in cui " api key " è scritta nell'immagine sopra, è possibile fornire un'intestazione specifica o un valore chiave se il progetto lo richiede come autenticazione basata su id utente, ecc. Per questo dovrai anche apportare modifiche in index.html sotto il tag che inizia con <input placeholder="api_key" ......

Un altro vantaggio di Swagger-UI è, fornisce un pulsante " Try it out! ". Questo pulsante ti consente di vedere quale potrebbe essere la risposta di questo webservice. In questo caso, se clicchiamo su quel pulsante, darà la seguente risposta sullo schermo:

Quindi questa è la demo di esempio per l'interfaccia utente di Swagger. Ci sono molte opzioni che puoi ancora scoprire mentre scrivi il controller REST che ti aiuterà a livello di documentazione usando più annotazioni e i loro attributi.