swagger
말다툼하다

비고

저지 REST WS를 가진 swagger-ui

Swagger 의 공식 웹 사이트는 다음과 같이 말했습니다 :

Swagger는 소스 코드, 문서 또는 네트워크 트래픽 검사를 사용하지 않고도 사람과 컴퓨터가 서비스의 기능을 발견하고 이해할 수있게 해주는 REST API에 대한 표준 언어 독립형 인터페이스를 정의하는 것입니다. Swagger를 통해 올바르게 정의 된 소비자는 최소한의 구현 로직으로 원격 서비스를 이해하고 상호 작용할 수 있습니다. 저수준 프로그래밍을 위해 인터페이스가했던 것과 비슷하게, Swagger는 서비스를 호출 할 때의 추측을 제거합니다.

Maven과 jersey를 사용한다고 가정하면 다음과 같은 종속성을 추가해야합니다. Maven Swagger Dependency 와 JAX-RS의 종속성. 이제 "maven webapp"를 만들어야하고 webapp 아래 에이 URL 에있는 내용을 붙여 넣어야합니다. webapp의 폴더 구조는 프로젝트에 해당 내용을 붙여 넣은 후에 다음과 같이 나타납니다.

그 후에이 단계를 따르십시오.

1. 아래와 같이 모든 이름 (이 경우에는 " ApiOriginFilter.java ")을 사용하여 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 {
    }
}

이 파일은 클래스에서 제공되는 들어오는 요청을 필터링합니다.

2. 다음과 같이 이름이 " 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);
}
}

위에서 볼 수 있듯이, 위의 클래스에서 우리는 호스트처럼 사용자 정의 된 UI를 사용하는 데 필요한 모든 세부 정보를 제공했습니다.이 멋진 프로젝트는 사용자가 선택한 기본 경로를 설정하는 기능과 함께 호스팅되며 " http "또는 " https "및 귀하의 요구 사항에 따라 더 자세한 정보를 제공합니다. Swagger가 패키지와 함께 setResourcePackage 를 사용하여 설정할 수있는 REST WS의 위치를 ​​모두 알도록하는 조항도 있습니다.이 클래스를 사용하면 사용자 정의 UI에서 Swagger UI를 사용할 수 있습니다.

이제 web.xml에 2 개 이상의 파일을 입력하여 다음과 같이 서버에 응용 프로그램을 배포 한 후 사용하십시오.

<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에서 제공하는 주석을 사용하는 실제 코드로 이동합니다.

아래와 같이 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") - Swagger UI에 표시해야하는 Bean 클래스의 이름을 결정합니다.
2. @ApiModelProperty(value ="ABC", example="DeptName") - 빈에서 사용되는 각 필드의 정보를 제공합니다. 값은 필드에 대한 설명을 제공하며 예제는 해당 필드의 샘플 값을 제공합니다.

이제 다음과 같이 GET webservice를 작성하기 위해 REST Controller를 작성한다.

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를 작성하는 동안의 몇 가지 표준은 " GetEmployee "또는 " DeleteEmployee "등과 같이 제목이 아닌 Swagger Documentation을 쓰는 동안 적용 가능하다는 점에 유의하십시오.
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 상태 코드를 처리합니다. 이를 통해 우리는 오류 코드, 사용자 정의 메시지를 설정할 수 있으며 필요한 경우 별도의 오류 클래스에서 해당 오류를 잡을 수도 있습니다.

마지막으로 클라이언트가 웹 서비스를 사용할 때 직원의 세부 정보를 가져올 실제 Service 클래스를 만들어야합니다. 필요에 따라 구현할 수 있습니다. 다음은 데모 목적을위한 샘플 서비스입니다.

public class EmployeeService {

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

이제 Swagger UI에 대한 설명서를 볼 준비가되었습니다. Swagger 프로젝트를 전개하고 서버를 시작하십시오. 이제 브라우저로 가서 프로젝트의 URL을 누르십시오. 이 경우에

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

swagger가 제대로 구성된 경우 다음 화면을 볼 수 있어야합니다.

이제 웹 서비스 문서가 텍스트 상자 ( http://exampl.com/api)에 프로젝트의 "base_url / rest / swagger.json"을 제공합니다. 위 이미지에서 볼 수 있습니다. 해당 URL을 텍스트 상자에 입력하면 REST 웹 서비스 문서를 제공하는 다음 화면을 볼 수 있습니다.

위의 그림에서 " api key "라고 쓰여진 글 상자는 프로젝트가 사용자 ID 등을 기반으로하는 인증을 요구한다면 특정 헤더 나 키 값을 제공 할 수 있습니다. 이를 위해 <input placeholder="api_key" ...... 시작하는 태그 아래에서 index.html을 변경해야합니다.

Swagger-UI의 또 다른 추가 이점은 " Try it out! "버튼을 제공 Try it out! . 이 버튼을 사용하면이 웹 서비스의 응답을 확인할 수 있습니다. 이 경우 해당 버튼을 클릭하면 화면에 다음과 같은 응답이 표시됩니다.

Swagger UI의 샘플 데모입니다. 더 많은 주석과 속성을 사용하여 문서 수준에서 도움이 될 REST 컨트롤러를 작성하는 동안 발견 할 수있는 많은 옵션이 있습니다.