Table of Contents
On this page

Writing documentation

Summary

OpenAPI attributes live in a dedicated OpenAPI.php file per module rather than in the handlers themselves. This page lists the request attributes (OA\Get, OA\Post, OA\Patch, OA\Put, OA\Delete), the component objects that describe payloads (OA\Schema, OA\Parameter, OA\RequestBody), and the parameters each request attribute should define.

Details

To avoid polluting PHP files with maybe thousands of lines of OpenAPI attributes, we opted for storing them in separate files, called OpenAPI.php, one for each module.

We already covered all the endpoints available in Dotkernel API, you can consult the existing documentation in each module's own OpenAPI.php file. After you add more functionalities to your API, you will have to document the new endpoints. This is easier than it sounds because in most cases you will do the same: add a request by method, describe the request payload (if any), add request parameters (if any) and describe the possible responses.

Common objects

To do this, you will use the following request objects:

  • OA\Delete: delete an API resource identified by its unique id
  • OA\Get: fetch API single or collections of API resources
  • OA\Post: create a new API resource (unless if it already exists)
  • OA\Patch: update an existing API resource
  • OA\Put: create a new API resource (if it already exists, it is overwritten)

Also, the following components describe PHP objects:

  • OA\Schema: describe an object sent in a request or received as a response - read more
  • OA\Parameter: describe a query/path parameter - read more
  • OA\RequestBody: describe the body of a request - read more

There are a lot more, but these are the most often used ones.

If you need help, take a look at the existing definitions found in Dotkernel API.

OA\Delete

Defines a DELETE HTTP request. It should specify at least the following parameters:

  • path: the route to the resource (example: /resource/{id} - where id is a path parameter defined below)
  • description: verbose description of the endpoint's purpose
  • summary: short description of the endpoint's purpose
  • security: an array of security scheme(s) to be used—omit if the endpoint is not protected
  • tags: an array of tags to help group related requests (example: user-related requests could have a User tag)
  • parameters: an array of query/path parameters - each parameter is specified as a new OA\Parameter object
  • responses: an array of OA\Response objects, each describing a combination of HTTP status codes and their respective response bodies

OA\Get

Defines a GET HTTP request. It should specify at least the following parameters:

  • path: the route to a single or collection of resources (example: /resource/{id} for a single resource or /resource for a collection of resources)
  • description: verbose description of the endpoint's purpose
  • summary: short description of the endpoint's purpose
  • security: an array of security scheme(s) to be used—omit if the endpoint is not protected
  • tags: an array of tags to help group related requests (example: user-related requests could have a User tag)
  • parameters: an array of query/path parameters - each parameter is specified as a new OA\Parameter object
  • responses: an array of OA\Response objects, each describing a combination of HTTP status codes and their respective response bodies

OA\Patch

Defines a PATCH HTTP request. It should specify at least the following parameters:

  • path: the route to the resource (example: /resource/{id} - where id is a path parameter defined below)
  • description: verbose description of the endpoint's purpose
  • summary: short description of the endpoint's purpose
  • security: an array of security scheme(s) to be used—omit if the endpoint is not protected
  • requestBody: a OA\RequestBody object describing the data being sent in the request
  • tags: an array of tags to help group related requests (example: user-related requests could have a User tag)
  • parameters: an array of query/path parameters - each parameter is specified as a new OA\Parameter object
  • responses: an array of OA\Response objects, each describing a combination of HTTP status codes and their respective response bodies

OA\Post

Defines a POST HTTP request. It should specify at least the following parameters:

  • path: the route to the resource (example: /resource/{id} - where id is a path parameter defined below)
  • description: verbose description of the endpoint's purpose
  • summary: short description of the endpoint's purpose
  • security: an array of security scheme(s) to be used—omit if the endpoint is not protected
  • requestBody: a OA\RequestBody object describing the data being sent in the request
  • tags: an array of tags to help group related requests (example: user-related requests could have a User tag)
  • parameters: an array of query/path parameters - each parameter is specified as a new OA\Parameter object
  • responses: an array of OA\Response objects, each describing a combination of HTTP status codes and their respective response bodies

OA\Put

Defines a PUT HTTP request. It should specify at least the following parameters:

  • path: the route to the resource (example: /resource/{id} - where id is a path parameter defined below)
  • description: verbose description of the endpoint's purpose
  • summary: short description of the endpoint's purpose
  • security: an array of security scheme(s) to be used—omit if the endpoint is not protected
  • requestBody: a OA\RequestBody object describing the data being sent in the request
  • tags: an array of tags to help group related requests (example: user-related requests could have a User tag)
  • parameters: an array of query/path parameters - each parameter is specified as a new OA\Parameter object
  • responses: an array of OA\Response objects, each describing a combination of HTTP status codes and their respective response bodies

Conclusion

To summarize, the typical scenario on working on your own instance of Dotkernel API would follow these steps:

  • create new module (example: Book)
  • add functionality to your new module (routes, entities, repositories, handlers, services, tests etc)
  • create file OpenAPI.php in the new module and describe each new endpoint
  • generate the latest version of a documentation file as described in this tutorial

FAQ

Q: Why are the attributes not placed on the handlers?

A: A fully documented endpoint can run to hundreds of lines of attributes. Keeping them in a per-module OpenAPI.php leaves the handlers readable.

Q: Where do I start when documenting a new module?

A: Copy the shape of an existing module's OpenAPI.php. All the endpoints shipped with Dotkernel API are documented there and serve as working examples.

Q: Which parameters should every request attribute define?

A: path, description, summary, tags, parameters and responses, plus requestBody for the methods that accept a body, and security when the endpoint is protected.

Q: How do I document an unprotected endpoint?

A: Omit the security parameter.

Q: What is the difference between description and summary?

A: summary is a short one-line label; description is the verbose explanation. Renderers display them in different places.

Q: What are tags used for?

A: Grouping related endpoints in the rendered documentation — for example tagging every user endpoint with User.

Q: When do I use OA\Post versus OA\Put?

A: OA\Post creates a new resource, while OA\Put creates it and overwrites an existing one.

Q: Where do I find attributes not covered here?

A: In the OpenAPI specification and zircote/swagger-php's examples. See Getting help.

Q: What is the order of work when adding a documented feature?

A: Create the module, build its functionality, describe the endpoints in its OpenAPI.php, then regenerate the documentation file. See Generate documentation.