swagger
swagger-ui

Anmärkningar

swagger-ui med tröja REST WS

Som den officiella webbplatsen för Swagger säger:

Swagger ska definiera ett standard, språk-agnostiskt gränssnitt till REST-API: er som gör att både människor och datorer kan upptäcka och förstå tjänstens funktioner utan tillgång till källkod, dokumentation eller genom nätverkstrafikinspektion. När den definieras korrekt via Swagger kan en konsument förstå och interagera med fjärrtjänsten med en minimal mängd implementeringslogik. I likhet med vad gränssnitt har gjort för programmering på lägre nivå, tar Swagger bort gissningen när den ringer till tjänsten.

Förutsatt att du använder Maven och jersey, kommer du att kräva följande beroende: Maven Swagger Dependency tillsammans med JAX-RS-beroenden. Nu måste du skapa "maven webapp" och under webapp måste du klistra in innehåll som finns på denna URL . Mappstrukturen för webapp ska se ut så här när du klistrar in innehållet i ditt projekt:

Följ sedan dessa steg:

1. Skapa en java-fil med vilket namn som helst (i vårt fall " ApiOriginFilter.java ") som liknar nedan:

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

Denna fil kommer att se till att filtrera de inkommande förfrågningarna enligt klassen.

2. Skapa en java-fil med alla namn antar att i vårt fall heter " SwaggerJaxrsConfig.java " enligt följande:

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

Som ni kan se, i ovanstående klass har vi tillhandahållit alla detaljer som krävs för att använda swagger UI som Host där detta swaggerprojekt kommer att vara värd tillsammans med möjlighet att ställa in basväg efter ditt val och alla http-protokoll som stöds som " http " eller " https " och ännu mer information enligt dina krav. Det finns också bestämmelser för att låta Swagger veta alla dina REST WS-platser som kan ställas in med setResourcePackage tillsammans med paket. Den här klassen gör det möjligt för oss att använda Swagger UI med vår anpassning.

Ange nu över två filer i web.xml för att använda dem efter att ha implementerat vår applikation på servern som följer:

<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 kommer vi att flytta till den faktiska koden där vi kommer att använda Swagger-kommentarer:

Skapa en bean Employee.java enligt nedan:

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

Komponenterna i Swagger som vi använde här är:

1. @ApiModel("Employee bean") - Detta kommer att bestämma namnet på Bean-klassen som måste visas i Swagger UI.
2. @ApiModelProperty(value ="ABC", example="DeptName") - Detta ger information om varje fält som används i bönan. värde ger beskrivning av fältet och exempel ger provvärde för det fältet.

Nu skapar vi en REST Controller enligt följande för att skapa en GET webservice enligt följande:

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

Komponenterna i Swagger som vi använde här är:

1. @Api(tags = {"Employee"}) - Den här kommentaren säger Swagger vad som ska vara titeln på webbtjänsten. I detta fall är titeln " Employee ". Observera att få standarder när du skriver REST WS också är tillämpliga när du skriver Swagger-dokumentation som titel bör inte vara som " GetEmployee " eller " DeleteEmployee ", etc.
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - Den här kommentaren ger en kort idé om din webbtjänst.
   • produces beskriver svarformat,
   • value beskriver en kort idé om webbtjänsten
   • notes beskriver detaljerad information om denna webbtjänst i händelse av något.
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) }) - Dessa kommentarer ger oss ett sätt att hantera olika typer av HTTP statuskoder som kan tas emot som ett svar när du konsumerar denna webbtjänst. Det tillåter oss att ställa in felkoden, anpassade meddelanden mot det och tillåter oss även att fånga det felet i en separat felklass, om det behövs.

Slutligen måste vi skapa faktiska serviceklasser som hämtar information om anställda när webbtjänsten konsumeras av klienten. Du kan implementera det efter behov. Följande är provtjänsten för demoändamål:

public class EmployeeService {

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

Nu är du redo att se din dokumentation om Swagger UI. Distribuera ditt Swagger-projekt och starta servern. Gå nu till webbläsaren och slå webbadressen till ditt projekt. I det här fallet

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

Om swagger är korrekt konfigurerad bör du kunna se följande skärm:

Nu kan du se projektets "base_url / rest / swagger.json" i textrutan ( http://exampl.com/api) för att se din webbtjänstdokumentation i textrutan ( http://exampl.com/api) . När du har angett den webbadressen i textrutan kan du se följande skärm med dokumentation av din REST-webbtjänst:

Textrutan där " api key " är skriven i ovanstående bild, du kan tillhandahålla specifikt sidhuvud eller nyckelvärde om ditt projekt kräver det som autentisering baserat på användar-ID osv. För det måste du också göra ändringar i index.html under taggen som börjar med <input placeholder="api_key" ......

En annan fördel med Swagger-UI är att det ger en knapp " Try it out! ". Med den här knappen kan du se vad som kan vara svaret på denna webbtjänst. För detta fall, om vi klickar på den knappen, kommer det att ge följande svar på skärmen:

Så detta är exempeldemo för Swagger UI. Det finns många alternativ som du fortfarande kan upptäcka när du skriver REST-kontroller som hjälper dig på dokumentationsnivå genom att använda fler kommentarer och deras attribut.