README

简介

RESTFul API提供了一个简单的框架，使得实现OpenApi 2（版本3即将推出）服务器变得相对简单。

实际上，该库仅支持OpenApi 2功能的一部分，但我们会在此期间添加更多。

安装

如果您想编写使用RESTFul API的应用程序，您必须使用Composer安装它。为此，只需将其添加到composer.json中的依赖项即可。

{
    "require": {
        "appserver-io/restapi": "~1.0"
    }
}

配置

只需在WEB-INF/web.xml文件中注册两个servlet AppserverIo\RestApi\Servlets\SwaggerServlet 和 AppserverIo\RestApi\Servlets\ApiServlet。您可以通过Rob Allens库 zircote/swagger-php 的注解来完成您Web服务的详细描述。

Servlet配置

配置必须在如本示例所示的WEB-INF/web.xml文件中完成。

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://www.appserver.io/appserver">

    <display-name>my-api</display-name>
    <description>My API web application</description>

    <session-config>
        <session-name>my-api/session-name>
        <session-file-prefix>my-api_session_</session-file-prefix>
    </session-config>

    <servlet>
        <description>A servlet that handles DHTML files.</description>
        <display-name>The DHTML Servlet</display-name>
        <servlet-name>dhtml</servlet-name>
        <servlet-class>AppserverIo\Appserver\ServletEngine\Servlets\DhtmlServlet</servlet-class>
    </servlet>

    <servlet>
        <description>A servlet that renders the content of the Swagger definition.</description>
        <display-name>The Swgger Servlet</display-name>
        <servlet-name>swagger</servlet-name>
        <servlet-class>AppserverIo\RestApi\Servlets\SwaggerServlet</servlet-class>
    </servlet>

    <servlet>
        <description>A servlet that handles the RESTFul API requests.</description>
        <display-name>The API Servlet</display-name>
        <servlet-name>api</servlet-name>
        <servlet-class>AppserverIo\RestApi\Servlets\ApiServlet</servlet-class>
        <bean-ref>
            <bean-ref-name>RequestHandlerFactory</bean-ref-name>
            <bean-link>RequestHandlerFactory</bean-link>
            <injection-target>
                <injection-target-class>AppserverIo\RestApi\Servlets\ApiServlet</injection-target-class>
                <injection-target-property>requestHandlerFactory</injection-target-property>
            </injection-target>
        </bean-ref>
        <init-param>
          <param-name>api</param-name>
          <param-value>OA2</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>dhtml</servlet-name>
        <url-pattern>*.dhtml</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>swagger</servlet-name>
        <url-pattern>/swagger.do</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>api</servlet-name>
        <url-pattern>/api.do</url-pattern>
    </servlet-mapping>

    <!-- ================================================================== -->
    <!-- Error Page Configuration                                           -->
    <!-- ================================================================== -->

    <error-page>
        <error-code-pattern>500</error-code-pattern>
        <error-location>/dhtml/500.dhtml</error-location>
    </error-page>

</web-app>

注解Beans

在配置好web应用程序后，只需使用必要的注解（如）注解您希望公开为Web服务器的类。

/**
 * A SLSB implementation providing some API functionality.
 *
 * @EPB\Stateless
 *
 * @SWG\Info(
 *     title="My API",
 *     version="1.0.0"
 * )
 *
 * @SWG\Swagger(
 *   schemes={"http"},
 *   host="127.0.0.1:9080",
 *   basePath="/my-api/api.do"
 * )
 */
class SomeProcessor
{

    /**
     * Returns the DTO with the passed ID.
     *
     * @param integer $id The ID of the DTO to return
     *
     * @return \Ma\Api\Dtos\MyDto The DTO with the data
     *
     * @SWG\Get(
     *     path="/traveltaxpackages/{id}",
     *     operationId="find",
     *     produces={"application/json"},
     *     @SWG\Parameter(
     *         name="id",
     *         in="path",
     *         description="The ID of the DTO to return",
     *         required=true,
     *         type="integer"
     *     ),
     *     @SWG\Response(
     *         response="200",
     *         description="The DTO",
     *         @SWG\Schema(
     *             ref="#/definitions/MyDto"
     *         )
     *     )
     * )
     */
    public function find($id)
    {
        // return an array with serializable DTOs here
    }
}

用法

打开浏览器，输入URL http://127.0.0.1:9080/my-api/swagger.do，应该会渲染Swagger配置。