https://github.com/appserver-io/restapi
Servlet based library that provides basic functionality to implement an API that is compatible with the OpenAPI 2.0 specification.
https://github.com/appserver-io/restapi
Last synced: 4 months ago
JSON representation
Servlet based library that provides basic functionality to implement an API that is compatible with the OpenAPI 2.0 specification.
- Host: GitHub
- URL: https://github.com/appserver-io/restapi
- Owner: appserver-io
- Created: 2018-09-13T14:30:17.000Z (almost 8 years ago)
- Default Branch: 2.0.x
- Last Pushed: 2021-05-03T10:28:28.000Z (about 5 years ago)
- Last Synced: 2024-11-24T17:28:15.063Z (over 1 year ago)
- Language: PHP
- Size: 48.8 KB
- Stars: 0
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# RESTFul API
[](https://packagist.org/packages/appserver-io/restapi)
[](https://packagist.org/packages/appserver-io/restapi)
[](https://packagist.org/packages/appserver-io/restapi)
[](https://travis-ci.org/appserver-io/restapi)
[](https://scrutinizer-ci.com/g/appserver-io/restapi/?branch=master)
[](https://scrutinizer-ci.com/g/appserver-io/restapi/?branch=master)
## Introduction
RESTFul API provides a simple framework that makes the implemention of a OpenApi 2 (verion 3 is still to come) server pretty simple.
Actually the library only supports a subset of the OpenApi 2 functionality, but we'll add additional during the time.
## Installation
If you want to write an application that uses RESTFul API, you have to install it using Composer. To do this, simply add it to the dependencies in your `composer.json`
```sh
{
"require": {
"appserver-io/restapi": "~1.0"
}
}
```
## Configuration
Simply register the two servlets `AppserverIo\RestApi\Servlets\SwaggerServlet` and `AppserverIo\RestApi\Servlets\ApiServlet` in the `WEB-INF/web.xml` file. The main
description of your webservices can be done through the annotations of Rob Allens library [zircote/swagger-php](https://github.com/zircote/swagger-php/tree/2.x).
### The Servlet Configuration
The configuration has to be done in the `WEB-INF/web.xml` file as shown in this example
```xml
my-api
My API web application
my-api/session-name>
my-api_session_
A servlet that handles DHTML files.
The DHTML Servlet
dhtml
AppserverIo\Appserver\ServletEngine\Servlets\DhtmlServlet
A servlet that renders the content of the Swagger definition.
The Swgger Servlet
swagger
AppserverIo\RestApi\Servlets\SwaggerServlet
A servlet that handles the RESTFul API requests.
The API Servlet
api
AppserverIo\RestApi\Servlets\ApiServlet
RequestHandlerFactory
RequestHandlerFactory
AppserverIo\RestApi\Servlets\ApiServlet
requestHandlerFactory
api
OA2
dhtml
*.dhtml
swagger
/swagger.do
api
/api.do
500
/dhtml/500.dhtml
```
### Annotate the Beans
After the web application has been configured, simple annotate the classes that you want to expose as
webserver with the necessary annotations like
```php
/**
* 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
}
}
```
## Usage
Open the browser and enter the URL [http://127.0.0.1:9080/my-api/swagger.do](http://127.0.0.1:9080/my-api/swagger.do) which should result in
rendering the Swagger configuration.