Поиск…


замечания

Приятно, если у вас есть много идей по следующим компонентам:

Концепции REST WS (JAX-RS) Использование аннотаций API-интерфейс REST API API Maven и его зависимость

swagger-ui с майкой REST WS

Как сообщает официальный сайт Swagger :

Swagger должен определить стандартный, язык-агностический интерфейс для REST API, который позволяет как людям, так и компьютерам обнаруживать и понимать возможности службы без доступа к исходному коду, документации или проверке сетевого трафика. При правильном определении через Swagger потребитель может понимать и взаимодействовать с удаленным сервисом с минимальной логикой реализации. Подобно тем, какие интерфейсы выполняли для программирования более низкого уровня, Swagger удаляет догадки при вызове службы.

Предполагая, что вы используете Maven и трикотаж, вам потребуется следующая зависимость: Maven Swagger Dependency и зависимости JAX-RS. Теперь вам нужно создать «maven webapp», а под webapp вам нужно вставить содержимое, присутствующее в этом URL-адресе . Структура папок webapp должна выглядеть следующим образом после вставки этого содержимого в ваш проект:

введите описание изображения здесь

После этого выполните следующие действия:

  1. Создайте java-файл с любым именем (в нашем случае его « ApiOriginFilter.java »), как 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 {
    }
}

Этот файл обеспечит фильтрацию входящих запросов, как это предусмотрено в классе.

  1. Создайте java-файл любого имени, предположим, в нашем случае его имя « SwaggerJaxrsConfig.java » выглядит следующим образом:
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);
}
}

Как вы можете видеть, в вышеприведенном классе мы предоставили все детали, необходимые для использования пользовательского интерфейса swagger, такого как Host, на котором будет размещен этот проект swagger, а также средство для установки базового пути по вашему выбору и всех поддерживаемых HTTP-протоколов, таких как « http » или « https » и даже более подробные сведения в соответствии с вашим требованием. Также есть возможность позволить Swagger узнать все ваше местоположение REST WS, которое может быть установлено с помощью setResourcePackage вместе с пакетами. Этот класс позволяет нам использовать интерфейс Swagger с нашей настройкой.

Теперь сделайте запись над 2 файлами в web.xml, чтобы использовать их после развертывания нашего приложения на сервере, например:

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

Теперь мы перейдем к фактическому коду, где мы будем использовать Swagger, предоставленный Аннотации:

Создайте bean Employee.java, как показано ниже:

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

Компоненты Swagger, которые мы использовали здесь:

  1. @ApiModel("Employee bean") - это будет определять имя класса Bean, которое должно отображаться в пользовательском интерфейсе Swagger.
  2. @ApiModelProperty(value ="ABC", example="DeptName") - Это будет предоставлять информацию о каждом поле, используемом в компоненте. value предоставляет описание поля, а пример предоставляет примерное значение этого поля.

Теперь мы создадим REST-контроллер следующим образом, чтобы создать веб-сервис GET следующим образом:

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

Компоненты Swagger, которые мы использовали здесь:

  1. @Api(tags = {"Employee"}) Эта аннотация сообщит Swagger, что должно быть названием веб-службы. В этом случае титул « Employee ». Обратите внимание, что при написании REST WS применяется несколько стандартов при написании документации Swagger, например, название должно быть не таким, как « GetEmployee » или « DeleteEmployee » и т. Д.
  2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - В этой аннотации приводится краткая идея о вашем веб-сервисе.
    • produces описывает формат ответа,
    • value описывает краткое представление о веб-сервисе
    • notes описывают подробную информацию об этом веб-сервисе в случае их возникновения.
  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) }) - Эти аннотации предоставляют нам способ обрабатывать различные типы кодов состояния HTTP которые могут быть получены в качестве ответа при использовании этого веб-сервиса. Это позволяет нам установить код ошибки, настраиваемое сообщение против него и даже позволить нам поймать эту ошибку в отдельном классе ошибок, если это необходимо.

Наконец, мы должны создать фактический класс обслуживания, который будет получать сведения о сотрудниках, когда веб-сервис потребляется клиентом. Вы можете реализовать его по мере необходимости. Ниже приведен пример сервиса для демонстрационной цели:

public class EmployeeService {

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

Теперь вы готовы просмотреть свою документацию по пользовательскому интерфейсу Swagger. Разверните проект Swagger и запустите сервер. Теперь перейдите в браузер и нажмите URL вашего проекта. В этом случае его

HTTP: // локальный: 8080 / чванство-щ /

Если чванство настроено правильно, вы должны увидеть следующий экран:

Приветственная страница Swagger-UI

Теперь, чтобы увидеть вашу документацию по webservice, укажите «base_url / rest / swagger.json» вашего проекта в текстовом поле ( http://exampl.com/api), которое вы можете увидеть на изображении выше. После предоставления этого URL-адреса в текстовом поле вы можете увидеть следующий экран, содержащий документацию вашего веб-сервиса REST:

введите описание изображения здесь

Текстовое поле, в котором « api key » написано на изображении выше, вы можете указать определенный заголовок или ключевое значение, если ваш проект требует его аутентификации на основе идентификатора пользователя и т. Д. Для этого вам также необходимо внести изменения в index.html под тегом, начинающимся с <input placeholder="api_key" ......

Еще одно преимущество Swagger-UI - это кнопка « Try it out! ». Эта кнопка позволяет вам увидеть, что может быть ответом этого веб-сервиса. В этом случае, если мы нажмем на эту кнопку, на экране появится следующий ответ:

введите описание изображения здесь

Итак, это демонстрационная демонстрация для пользовательского интерфейса Swagger. Есть много вариантов, которые вы все еще можете обнаружить при написании контроллера REST, который поможет вам на уровне документации, используя больше аннотаций и их атрибутов.



Modified text is an extract of the original Stack Overflow Documentation
Лицензировано согласно CC BY-SA 3.0
Не связан с Stack Overflow