swagger
スワッガーユー

備考

ジャージーREST WSを持つswagger-ui

Swaggerの公式ウェブサイトによれば、

Swaggerは、人間とコンピュータの両方がソースコード、ドキュメンテーション、またはネットワークトラフィックインスペクションにアクセスすることなく、サービスの機能を発見し理解することを可能にする、REST APIに対する標準の言語に依存しないインタフェースを定義することです。 Swaggerを使用して適切に定義すると、消費者は最小限の実装ロジックでリモートサービスを理解し、対話できます。 Swaggerは、下位レベルのプログラミングのためのインターフェースと同様に、サービスを呼び出す際の推測を削除します。

Mavenとジャージを使用すると仮定すると、以下の依存関係を追加する必要があります： 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 "であると仮定して、任意の名前の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);
}
}

あなたが見ることができるように、上記のクラスでは、我々はこの闊歩プロジェクトは、お好みのベースパスを設定する機能と一緒にホストされるどのホストのように闊歩のUIを使用するために必要なすべての詳細と「のようにサポートされているすべてのHTTPプロトコルを提供していhttp 」か" https "、そしてあなたの要求に応じてより詳細な情報を提供します。また、Swaggerにパッケージと一緒にsetResourcePackageを使用して設定できるREST WSの場所をすべて知らせるための規定があります。

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で提供されるアノテーションを使用する実際のコードに移動します。

次のようにして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") - Swagger UIに表示する必要があるBeanクラスの名前を決定します。
2. @ApiModelProperty(value ="ABC", example="DeptName") - これは、Beanで使用される各フィールドの情報を提供します。値はフィールドの説明を提供し、例はそのフィールドのサンプル値を提供します。

ここでは、次のようにGET Webサービスを作成するためのRESTコントローラを作成します。

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"}) - このアノテーションは、WebサービスのタイトルとなるべきものをSwaggerに通知します。この場合、タイトルは「 Employee 」です。タイトルのようなSwaggerドキュメンテーションを書いている間は、 " GetEmployee "や " DeleteEmployee "のようにすべきではありません。
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - この注釈は、あなたのwebserviceについて。
   • producesは応答の形式を記述し、
   • valueはウェブサービスに関する簡単なアイデアを記述する
   • notesは、このWebサービスに関する詳細情報が記載されています。
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) }) - この注釈は、このWebサービスを消費している間に応答として受け取ることができるさまざまなタイプのHTTPステータスコードを処理します。これにより、エラーコードとそれに対するカスタムメッセージを設定することができます。また、必要に応じて別のエラークラスでエラーをキャッチすることもできます。

最後に、Webサービスがクライアントによって消費されたときに従業員の詳細を取得する実際の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 /

スワッガーが正しく構成されている場合、次の画面が表示されるはずです。

さて、あなたのWebサービスのドキュメントを見るには、上記の画像で見ることができるテキストボックス（ http://exampl.com/api）のプロジェクトの "base_url / rest / swagger.json"を提供してください。そのURLをテキストボックスに入力すると、REST Webサービスのドキュメントを提供する次の画面が表示されます。

上記の画像に「 api key 」と書かれたテキストボックスでは、ユーザIDなどに基づいた認証のようなプロジェクトが必要な場合は、特定のヘッダーやキー値を指定できます。そのためには、 <input placeholder="api_key" ......始まるタグの下でindex.htmlを変更する必要もあります。

Swagger-UIのもう1つの利点は、「 Try it out! 」というボタンがあるTry it out! 。このボタンを使用すると、このWebサービスの応答が何であるかを確認できます。この場合、そのボタンをクリックすると、画面上で次のような応答が表示されます。

これはSwagger UIのサンプルデモです。より多くの注釈とそれらの属性を使用することで、ドキュメントレベルでお手伝いするRESTコントローラを記述する際に、まだ発見できる多くのオプションがあります。