Download the PHP package lucite/apispec without Composer

lucite/apispec

A library for building an mostly unopinionated openapi specifications, with additional functions for building a strongly opinionated specification that can be easily connected to other php frameworks.

Unopinionated building blocks

The library provides set of classes for defining and connecting various parts of an openapi specification.

For example, you can create a string property named title with a minimum length of 10 like this:

$titleProp = new Lucite\ApiSpec\Property('title', 'string', ['minLength' => 10]);

You could then add that to a schema named Employee like this:

$schema = (new Lucite\ApiSpec\Schema('Employee'))->addProperty($titleProp);

The root level of a specification is, unsurprisingly, a Specification object:

$spec = new Lucite\ApiSpec\Specification('myapi', 'v1.1');

Other classes that are provided:

• Path, which can be added to a Specification instance.
• Method, which can be added to a Path instance.
• PathParameter, which can be added to a Method instance.
• QueryParameter, which can be added to a Method instance.
• Response, which can be added to a Method instance.

While these classes do not allow for the construction of any possible openapi specification, they cover many common cases.

Opinionated structure

The Lucite\ApiSpec\Specification class has a number of shortcut methods that let you quickly build a highly opinionated API structure.

For a given resource type (say, a Book), one can easily add these 5 routes:

• GET /books/ which returns an array of zero or more Book resources
• GET /books/{bookId} which returns a single Book resource by id
• POST /books/ which creats a single Book resource
• PATCH /books/{bookId} which updates a single Book resource by id
• DELETE /books/{bookId} which deletes a single Book resource by id

To build something like this,

Request format

The POST and PATCH methods require a content-type: application/json header with a request body containing the following structure:

Reponse format

There are 4 response formats that may be returned from the above routes:

• A successful, single resource response such as:

  This structure is returned from successful requests to: GET /books/{bookId}, POST /books/, PATCH /books/{bookId}

• A successful collection of resources such as:

  This structure is returned from successful requests to: GET /books/

• An unsuccessul response such as:

  This format is returned from POST /books/ and PATCH /books/{bookId} when the request fails.

• An empty response with status code such as:
  • 401 Not Authorized
  • 404 Not Found
  • 204 Deleted

Usage in a framework

Writing specification json (yaml not supported)

Looping over routes to add them to an app

Here's an example of how to use a Specification instance to map routes in Lumen or Slim. Other frameworks are probably very similar.

Using Schema validators

Once a schema is defined, you can create a Lucite\ApiSpec\Validator from it. The validator takes an array and returns EITHER:

• a boolean true if the data passes validation
• an associative array of errors

Example:

You can get a validator for a schema from the specification object by schema name:

A good way to use this functionality would be to add the specification object to your dependency injection container, and then ->get() the spec/validator in a controller.