swagger
Swagger-Ui

Bemerkungen

Swagger-Ui mit Trikot REST WS

Wie die offizielle Website von Swagger sagt:

Swagger ist die Definition einer standardmäßigen, sprachunabhängigen Schnittstelle für REST-APIs, die es Menschen und Computern ermöglicht, die Funktionen des Dienstes ohne Zugriff auf Quellcode, Dokumentation oder durch die Überprüfung des Netzwerkverkehrs zu erkennen und zu verstehen. Wenn er über Swagger richtig definiert ist, kann er den Remote-Service mit einem Minimum an Implementierungslogik verstehen und mit ihm interagieren. Ähnlich wie bei den Schnittstellen für die untergeordnete Programmierung, entfernt Swagger die Rätselraten beim Aufruf des Dienstes.

Wenn Sie Maven und Trikot verwenden, müssen Sie folgende Abhängigkeit hinzufügen: Maven Swagger Abhängigkeit zusammen mit Abhängigkeiten von JAX-RS. Jetzt müssen Sie "maven webapp" erstellen und unter der Webapp müssen Sie den Inhalt dieser URL einfügen. Die Ordnerstruktur von webapp sollte nach dem Einfügen dieser Inhalte in Ihr Projekt folgendermaßen aussehen:

Danach folgen Sie diesen Schritten:

1. Erstellen Sie eine Java-Datei mit einem beliebigen Namen (in unserem Fall " ApiOriginFilter.java "), der wie ApiOriginFilter.java :

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

Diese Datei stellt sicher, dass die eingehenden Anforderungen entsprechend der Klasse gefiltert werden.

2. Erstellen Sie eine Java-Datei mit einem beliebigen Namen. In unserem Fall lautet der Name " SwaggerJaxrsConfig.java " wie folgt:

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

Wie Sie sehen können, haben wir in der obigen Klasse alle erforderlichen Informationen für die Verwendung der Swagger-Benutzeroberfläche wie Host bereitgestellt, auf der dieses Swagger-Projekt gehostet wird, sowie die Möglichkeit, den Basispfad Ihrer Wahl und alle unterstützten http-Protokolle wie " http " oder " https " und noch mehr Details je nach Anforderung. Es gibt auch die Möglichkeit, Swagger den gesamten Standort Ihres REST WS setResourcePackage , der mithilfe von setResourcePackage zusammen mit Paketen festgelegt werden setResourcePackage Mit dieser Klasse können wir die Swagger-Benutzeroberfläche mit unserer Anpassung verwenden.

Tragen Sie nun über 2 Dateien in web.xml ein, um sie nach der Bereitstellung unserer Anwendung auf dem Server wie folgt zu verwenden:

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

Jetzt gehen wir zum eigentlichen Code über, wo wir die von Swagger bereitgestellten Annotationen verwenden werden:

Erstellen Sie eine Bean Employee.java wie folgt:

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

Die Bestandteile von Swagger, die wir hier verwendet haben, sind:

1. @ApiModel("Employee bean") - Hiermit wird der Name der Bean-Klasse festgelegt, die auf der Swagger-Benutzeroberfläche angezeigt werden muss.
2. @ApiModelProperty(value ="ABC", example="DeptName") - Dies liefert Informationen zu jedem Feld, das in der Bean verwendet wird. value enthält eine Beschreibung des Felds und ein Beispiel liefert einen Beispielwert für dieses Feld.

Nun erstellen wir einen REST-Controller wie folgt, um einen GET-Webservice wie folgt zu erstellen:

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

Die Bestandteile von Swagger, die wir hier verwendet haben, sind:

1. @Api(tags = {"Employee"}) - Diese Anmerkung @Api(tags = {"Employee"}) Swagger mit, wie der Titel des Web-Services lauten soll. In diesem Fall lautet der Titel " Employee ". Bitte beachten Sie, dass wenige Standards beim Schreiben von REST WS auch beim Schreiben von Swagger-Dokumentationen wie dem Titel gelten, die nicht wie " GetEmployee " oder " DeleteEmployee " usw. DeleteEmployee .
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - Diese Anmerkung gibt eine kurze Idee über Ihren Webservice.
   • produces das Format der Antwort,
   • value beschreibt eine kurze Vorstellung des Webservice
   • notes beschreibt detaillierte Informationen zu diesem Webservice.
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) }) - Diese Anmerkungen geben uns einen Weg Behandeln Sie verschiedene Arten von HTTP Statuscodes, die als Antwort empfangen werden können, während Sie diesen Webservice nutzen. Es erlaubt uns, den Fehlercode und die benutzerdefinierte Nachricht dagegen zu setzen, und ermöglicht es uns sogar, diesen Fehler bei Bedarf in einer separaten Fehlerklasse abzufangen.

Schließlich müssen wir eine tatsächliche Service-Klasse erstellen, die die Details der Mitarbeiter abruft, wenn der Webservice vom Client in Anspruch genommen wird. Sie können es nach Bedarf implementieren. Im Folgenden finden Sie den Beispielservice für den Demo-Zweck:

public class EmployeeService {

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

Nun können Sie Ihre Dokumentation zur Swagger-Benutzeroberfläche anzeigen. Stellen Sie Ihr Swagger-Projekt bereit und starten Sie den Server. Gehen Sie jetzt zum Browser und klicken Sie auf die URL Ihres Projekts. In diesem Fall ist es

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

Wenn Swagger richtig konfiguriert ist, sollten Sie den folgenden Bildschirm sehen können:

Um Ihre Webservice-Dokumentation anzuzeigen, geben Sie im Textfeld ( http://exampl.com/api) das "base_url / rest / swagger.json" Ihres Projekts an, das Sie oben im Bild sehen. Nachdem Sie diese URL in einem Textfeld angegeben haben, können Sie den folgenden Bildschirm mit Dokumentation zu Ihrem REST-Webservice anzeigen:

Das Textfeld, in dem " api key " in das obige Bild geschrieben ist, können Sie einen bestimmten Kopf- oder Schlüsselwert angeben, wenn Ihr Projekt dies erfordert, z. B. eine Authentifizierung basierend auf der Benutzer-ID usw. Dazu müssen Sie auch Änderungen in index.html unter dem Tag vornehmen, der mit <input placeholder="api_key" ......

Ein weiterer zusätzlicher Vorteil von Swagger-UI ist die Schaltfläche " Try it out! ". Mit dieser Schaltfläche können Sie aktivieren, wie die Antwort dieses Webservice aussehen könnte. In diesem Fall wird beim Klicken auf diese Schaltfläche die folgende Antwort auf dem Bildschirm angezeigt:

Dies ist also die Beispiel-Demo für Swagger UI. Es gibt viele Optionen, die Sie beim Schreiben des REST-Controllers noch entdecken können, die Ihnen auf Dokumentationsebene durch die Verwendung weiterer Anmerkungen und ihrer Attribute helfen.