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