PHPackages                             alexcicioc/swagger-router - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. alexcicioc/swagger-router

ActiveLibrary[API Development](/categories/api)

alexcicioc/swagger-router
=========================

Handles routing and request/response validation as defined in an OpenApi spec

v1.1.7(6y ago)18982[1 PRs](https://github.com/alexcicioc/swagger-router/pulls)MITPHPPHP >=7.2.0

Since Jun 8Pushed 3y agoCompare

[ Source](https://github.com/alexcicioc/swagger-router)[ Packagist](https://packagist.org/packages/alexcicioc/swagger-router)[ RSS](/packages/alexcicioc-swagger-router/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (2)Versions (22)Used By (0)

swagger-router
==============

[](#swagger-router)

Swagger Router is a library that speeds up API development while having it documented.

It uses a json spec file compatible with [OpenAPI specification 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) and should support most of the features but if you find something missing feel free to open a pull request or an issue.

Install via composer:
---------------------

[](#install-via-composer)

`composer require alexcicioc/swagger-router`

Using swagger-router to bootstrap the API:
------------------------------------------

[](#using-swagger-router-to-bootstrap-the-api)

### Defining the endpoints using swagger

[](#defining-the-endpoints-using-swagger)

You'll need to define your API endpoints in the swagger spec. Here's a simple example you can use (it's in yaml for readability but should be converted to json):

**Recommendation:** You can use [Swagger Editor](http://editor.swagger.io/#/) to safely modify the spec then click on the File menu and "Convert and save to JSON".

```
swagger: '2.0'
info:
  version: 0.0.1
  title: Courses API
basePath: /api
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /courses:
    x-swagger-router-controller: Courses # used to route to the php controller class
    get:
      description: Returns a list of courses
      operationId: getCourses # used to route to the php controller method
      parameters:
        - $ref: '#/parameters/limitQuery'
        - $ref: '#/parameters/startIndexQuery'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/CourseList'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/courses/{courseId}':
    x-swagger-router-controller: Courses
    get:
      description: Returns a course
      operationId: getCourse # used to route to the php controller method
      parameters:
        - $ref: '#/parameters/courseIdPath'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Course'
        '404':
          description: Not Found
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'

definitions:

  CourseList:
    properties:
      results:
        type: array
        items:
          $ref: '#/definitions/Course'
    required:
      - results

  Course:
    properties:
      id:
        description: Course id
        type: integer
        minimum: 1
      title:
        description: Course title
        type: string
        maxLength: 255
      shortDescription:
        description: Short description
        type: string
        maxLength: 255
      longDescription:
        description: Long description
        type: string
      status:
        description: Course status
        type: string
        enum:
          - not-started
          - in-progress
          - complete
        default: not-started
    required:
      - id
      - title
      - shortDescription
      - longDescription
      - status

  ErrorResponse:
    required:
      - message
    properties:
      message:
        description: Error Message
        type: string

parameters:

  courseIdPath:
    in: path
    name: courseId
    type: integer
    minimum: 1
    required: true

  limitQuery:
    in: query
    name: limit
    type: integer
    default: 10

  startIndexQuery:
    in: query
    name: startIndex
    type: integer
    default: 0
```

### Redirecting the requests

[](#redirecting-the-requests)

You'll need to redirect everything to index.php. If you're using apache you can add this to your .htaccess file

```
RewriteEngine on
RewriteRule ^(.*)$ index.php [NC,L,QSA]

```

### Bootstrapping the app using swagger-router

[](#bootstrapping-the-app-using-swagger-router)

In index.php you'll have to build the SwaggerRouter instance. You can use this sample:

```
try {
    $app = new SwaggerRouter();
    // Validates and extracts the information from your swagger spec
    $app->use(new SpecParser('/app/swagger.json')); # Path to your spec
    // Optional - Handles the /swagger endpoint that exposes the spec to frontend apps
    $app->use(new SwaggerRawHandler());
    // Validates the called route, http method and content type
    $app->use(new RouteValidator());
    // Handles extracting the parameters from the request and formatting them
    $app->use(new ParamsHandler());
    // Optional - Validates the OAuth2 token given in the Authorization header
    $app->use(new OAuth(AuthorizationFactory::makeResourceServer()));
    // Optional - Handles validating the request parameters
    $app->use(new RequestValidator());
    // Routes the request to it's specific controller (given by x-swagger-router-controller)
    $app->use(new Router('\App\Api\Controllers')); # Controllers namespace (must be PSR-4 compliant)
    // Handles formatting the response
    $app->use(new ResponseHandler());
    // Optional - Handles validating the response
    $app->use(new ResponseValidator());

    $swaggerRequest = SwaggerRequest::fromGlobals(); // extends PSR-7 ServerRequest
    $swaggerResponse = new SwaggerResponse(); // extends PSR-7 Response
    $response = $app($swaggerRequest, $swaggerResponse);
    $response->send();
} catch (HttpException $e) {
    (new SwaggerResponse())
        ->withStatus($e->getCode())
        ->body((object)['message' => $e->getMessage()])
        ->send();
}
```

### Creating a controller

[](#creating-a-controller)

Previously in the spec we added these lines:

```
x-swagger-router-controller: Courses

```

```
operationId: getCourses

```

This tells swagger-router to search for the `Courses` controller and call the method `getCourses`

```
namespace App\Api\Controllers;

use Alexcicioc\SwaggerRouter\SwaggerRequest;
use Alexcicioc\SwaggerRouter\SwaggerResponse;

class Courses
{
    public function getCourses(SwaggerRequest $request, SwaggerResponse $response): SwaggerResponse
    {
        $filters = $request->getParam('technology');
        $limit = $request->getParam('limit');
        $startIndex = $request->getParam('startIndex');

        $results = [];
        // do db stuff here

        return $response
                ->withStatus(200)
                ->body((object)['results' => $results]);

    }

    public function getCourse(SwaggerRequest $request, SwaggerResponse $response): SwaggerResponse
    {
        $courseId = $request->getParam('courseId');

        $course = new \stdClass();
        $course->id = $courseId;
        // db stuff here

        return $response
                ->withStatus(200)
                ->body($course);
    }
}
```

Sample spec:
============

[](#sample-spec)

Laravel compatibility
=====================

[](#laravel-compatibility)

Swagger Router's middlewares are not compatible with Laravel's yet, however there's a workaround this.

Here's a sample Laravel middleware that calls the swagger router (not properly tested, may have some side effects):

```