swagger
branie-ui

Opmerkingen

swagger-ui met jersey REST WS

Zoals de officiële website van Swagger zegt:

Swagger moet een standaard, taal-agnostische interface definiëren voor REST API's waarmee zowel mensen als computers de mogelijkheden van de service kunnen ontdekken en begrijpen zonder toegang tot broncode, documentatie of via netwerkverkeerinspectie. Wanneer correct gedefinieerd via Swagger, kan een consument de externe service begrijpen en er interactie mee aangaan met een minimale hoeveelheid implementatielogica. Vergelijkbaar met wat interfaces hebben gedaan voor programmeren op een lager niveau, verwijdert Swagger het giswerk bij het aanroepen van de service.

Ervan uitgaande dat u Maven en jersey gebruikt, moet u de volgende afhankelijkheid toevoegen: Maven Swagger afhankelijkheid samen met de afhankelijkheden van JAX-RS. Nu moet u "maven webapp" maken en onder de webapp moet u de inhoud op deze URL plakken. De mappenstructuur van webapp moet er als volgt uitzien nadat u die inhoud in uw project hebt geplakt:

Volg daarna deze stappen:

1. Maak een Java-bestand met een willekeurige naam (in ons geval de " ApiOriginFilter.java ") die lijkt op onderstaande:

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

Dit bestand zorgt ervoor dat de inkomende verzoeken worden gefilterd zoals in de klasse is opgegeven.

2. Maak een Java-bestand met een willekeurige naam, veronderstel dat in ons geval de naam " SwaggerJaxrsConfig.java " als volgt is:

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

Zoals je kunt zien, hebben we in bovenstaande klasse alle details verstrekt die nodig zijn om swagger UI zoals Host te gebruiken waarop dit swaggerproject zal worden gehost, samen met de mogelijkheid om het basispad van uw keuze in te stellen en alle http-protocollen die worden ondersteund zoals " http " of " https " en zelfs meer details volgens uw vereiste. Er is ook een voorziening om Swagger alle locatie van uw REST WS te laten weten, die kan worden ingesteld met setResourcePackage samen met pakketten. Met deze klasse kunnen we Swagger UI gebruiken met onze aanpassing.

Voer nu meer dan 2 bestanden in web.xml in om ze te gebruiken na het implementeren van onze applicatie op de server zoals volgt:

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

Nu gaan we naar de werkelijke code waar we door Swagger verstrekte annotaties zullen gebruiken:

Maak een bean Employee.java zoals hieronder:

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

De componenten van Swagger die we hier hebben gebruikt zijn:

1. @ApiModel("Employee bean") - Dit bepaalt de naam van de Bean-klasse die moet worden weergegeven in de gebruikersinterface van Swagger.
2. @ApiModelProperty(value ="ABC", example="DeptName") - Dit geeft informatie over elk veld dat in de bean wordt gebruikt. waarde geeft een beschrijving van het veld en het voorbeeld geeft een voorbeeldwaarde van dat veld.

Nu maken we als volgt een REST-controller om een GET-webservice als volgt te maken:

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

De componenten van Swagger die we hier hebben gebruikt zijn:

1. @Api(tags = {"Employee"}) - Deze annotatie vertelt Swagger wat de titel van de webservice moet zijn. In dit geval is de titel " Employee ". Houd er rekening mee dat enkele normen tijdens het schrijven van REST WS ook van toepassing zijn tijdens het schrijven van Swagger-documentatie zoals titel, niet mogen zijn zoals " GetEmployee " of " DeleteEmployee ", enz.
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - Deze annotatie biedt een kort idee over uw webservice.
   • produces beschrijft het antwoordformaat,
   • value beschrijft kort idee over de webservice
   • notes beschrijft gedetailleerde informatie over deze webservice in het geval van een.
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) }) - Deze annotaties bieden ons een manier om verschillende soorten HTTP verwerken die als reactie kunnen worden ontvangen tijdens het gebruik van deze webservice. Het stelt ons in staat om de foutcode, het aangepaste bericht ertegen in te stellen en stelt ons zelfs in staat die fout indien nodig in een aparte foutklasse op te vangen.

Ten slotte moeten we een daadwerkelijke serviceklasse maken die de details van medewerkers ophaalt wanneer de webservice door de klant wordt gebruikt. U kunt het desgewenst implementeren. Hierna volgt de voorbeeldservice voor het Demo-doel:

public class EmployeeService {

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

Nu bent u klaar om uw documentatie op de gebruikersinterface van Swagger te bekijken. Implementeer uw Swagger-project en start de server. Ga nu naar de browser en klik op de URL van uw project. In dit geval is het

http: // localhost: 8080 / branie-ui /

Als swagger correct is geconfigureerd, zou je het volgende scherm moeten kunnen zien:

Om uw webservice-documentatie te zien, geeft u de "base_url / rest / swagger.json" van uw project in het tekstvak ( http://exampl.com/api) aan dat u in bovenstaande afbeelding kunt zien. Nadat u die URL in het tekstvak hebt opgegeven, ziet u het volgende scherm met documentatie van uw REST-webservice:

In het tekstvak waarin ' api key ' in de bovenstaande afbeelding is geschreven, kunt u een specifieke kop- of sleutelwaarde opgeven als uw project dit vereist, zoals authenticatie op basis van gebruikers-ID, enz. Daarvoor moet u ook wijzigingen aanbrengen in index.html onder de tag die begint met <input placeholder="api_key" ......

Een ander bijkomend voordeel van Swagger-UI is, het biedt een knop " Try it out! ". Met deze knop kunt u zien wat de reactie van deze webservice zou kunnen zijn. In dit geval zal het volgende antwoord op het scherm verschijnen als we op die knop klikken:

Dus dit is de voorbeelddemo voor Swagger UI. Er zijn nog veel opties die u tijdens het schrijven van de REST-controller kunt ontdekken, die u op documentatieniveau zullen helpen door meer annotaties en hun attributen te gebruiken.