OXIESEC PANEL

Name	Size	Modified	Perms
📁 ..	-	08/07/2024 04:34:25 AM	rwxr-xr-x
📄 annotations.md	3.44 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 attributes.md	1.14 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 common-techniques.md	6.98 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 cookbook.md	15.6 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 faq.md	5.25 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 generating-openapi-documents.md	1.91 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 index.md	990 bytes	08/07/2024 04:34:24 AM	rw-r--r--
📄 installation.md	455 bytes	08/07/2024 04:34:24 AM	rw-r--r--
📄 migrating-to-v3.md	1.74 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 migrating-to-v4.md	5.33 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 required-elements.md	1.11 KB	08/07/2024 04:34:24 AM	rw-r--r--
📄 under-the-hood.md	1.8 KB	08/07/2024 04:34:24 AM	rw-r--r--

Editing: required-elements.md

# 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:

<<< @/snippets/minimal_api_at.php

</template>
  <template v-slot:an>

<<< @/snippets/minimal_api_an.php

</template>
</codeblock>

with the resulting OpenAPI document like this

<<< @/snippets/minimal_api.yaml

::: warning 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`.