Swagger-PHP

Required elements

The OpenAPI specification defines a minimum set of information for a valid document.

For the most part that consists of some general information about the API like name, version and at least one endpoint.

The endpoint, in turn, needs to have a path and at least one response.

Minimum required annotations

With the above in mind a minimal API with a single endpoint could look like this:

with the resulting OpenAPI document like this

openapi: 3.0.0
info:
  title: 'My First API'
  version: '0.1'
paths:
  /api/data.json:
    get:
      operationId: 236f26ae21b015a60adbce41f8f316e3
      responses:
        '200':
          description: 'The data'

Code locations

Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs. These are limited to the extent of what the PHP Reflection APIs supports.

Optional elements

Looking at the generated document you will notice that there are some elements that swagger-php adds automatically when they are missing.

For the most part those are @OA\OpenApi, @OA\Components and @OA\PathItem.