From db238f2f9a8cf37471479834db5ed7fb80f5dba7 Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Tue, 4 Feb 2025 13:28:04 +0900 Subject: [PATCH 01/44] add in faq --- docs/guide/faq.md | 33 ++++++++-------------- docs/snippets/guide/faq/dummy_class_an.php | 21 ++++++++++++++ docs/snippets/guide/faq/dummy_class_at.php | 18 ++++++++++++ 3 files changed, 51 insertions(+), 21 deletions(-) create mode 100644 docs/snippets/guide/faq/dummy_class_an.php create mode 100644 docs/snippets/guide/faq/dummy_class_at.php diff --git a/docs/guide/faq.md b/docs/guide/faq.md index 87bf9d962..37fcc92dd 100644 --- a/docs/guide/faq.md +++ b/docs/guide/faq.md @@ -24,27 +24,18 @@ related code, the info annotation (and a few more) is kind of global. The simplest solution to avoid this issue is to add a 'dummy' class to the docblock and add all 'global' annotations (e.g. `Tag`, `Server`, `SecurityScheme`, etc.) **in a single docblock** to that class. -```php -/** - * @OA\Tag( - * name="user", - * description="User related operations" - * ) - * @OA\Info( - * version="1.0", - * title="Example API", - * description="Example info", - * @OA\Contact(name="Swagger API Team") - * ) - * @OA\Server( - * url="https://example.localhost", - * description="API server" - * ) - */ -class OpenApiSpec -{ -} -``` + + + + **As of version 4.8 the `doctrine/annotations` library is optional and might cause the same message.** diff --git a/docs/snippets/guide/faq/dummy_class_an.php b/docs/snippets/guide/faq/dummy_class_an.php new file mode 100644 index 000000000..7df8deb56 --- /dev/null +++ b/docs/snippets/guide/faq/dummy_class_an.php @@ -0,0 +1,21 @@ + Date: Tue, 11 Feb 2025 14:44:25 +0900 Subject: [PATCH 02/44] OAT to OA --- docs/snippets/guide/faq/dummy_class_at.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/snippets/guide/faq/dummy_class_at.php b/docs/snippets/guide/faq/dummy_class_at.php index 7e1a9ec92..3d1b0e9af 100644 --- a/docs/snippets/guide/faq/dummy_class_at.php +++ b/docs/snippets/guide/faq/dummy_class_at.php @@ -1,15 +1,15 @@ Date: Mon, 17 Feb 2025 22:09:18 +0900 Subject: [PATCH 03/44] x-tagGroups --- docs/guide/cookbook.md | 23 ++++++++++--------- .../guide/cookbook/x_tag_groups_an.php | 14 +++++++++++ .../guide/cookbook/x_tag_groups_at.php | 14 +++++++++++ 3 files changed, 40 insertions(+), 11 deletions(-) create mode 100644 docs/snippets/guide/cookbook/x_tag_groups_an.php create mode 100644 docs/snippets/guide/cookbook/x_tag_groups_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index cd722a95b..d63460fca 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -5,17 +5,18 @@ OpenApi has the concept of grouping endpoints using tags. On top of that, some t ([redocly](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/), for example) support further grouping via the vendor extension `x-tagGroups`. -```php -/** - * @OA\OpenApi( - * x={ - * "tagGroups"= - * {{"name"="User Management", "tags"={"Users", "API keys", "Admin"}} - * } - * } - * ) - */ -``` + + + + ## Adding examples to `@OA\Response` ```php diff --git a/docs/snippets/guide/cookbook/x_tag_groups_an.php b/docs/snippets/guide/cookbook/x_tag_groups_an.php new file mode 100644 index 000000000..c00047205 --- /dev/null +++ b/docs/snippets/guide/cookbook/x_tag_groups_an.php @@ -0,0 +1,14 @@ + [ + ['name' => 'User Management', 'tags' => ['Users', 'API keys', 'Admin']] + ] + ] +)] +class OpenApiSpec +{ +} From 92e294831d46827b5e8cdb21cb7caf061e30a395 Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Mon, 17 Feb 2025 22:14:00 +0900 Subject: [PATCH 04/44] response examples --- docs/guide/cookbook.md | 29 +++++++++---------- .../guide/cookbook/response_examples_an.php | 22 ++++++++++++++ .../guide/cookbook/response_examples_at.php | 24 +++++++++++++++ 3 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 docs/snippets/guide/cookbook/response_examples_an.php create mode 100644 docs/snippets/guide/cookbook/response_examples_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index d63460fca..06faab758 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -19,22 +19,19 @@ support further grouping via the vendor extension `x-tagGroups`. ## Adding examples to `@OA\Response` -```php -/* - * @OA\Response( - * response=200, - * description="OK", - * @OA\JsonContent( - * oneOf={ - * @OA\Schema(ref="#/components/schemas/Result"), - * @OA\Schema(type="boolean") - * }, - * @OA\Examples(example="result", value={"success": true}, summary="An result object."), - * @OA\Examples(example="bool", value=false, summary="A boolean value."), - * ) - * ) - */ -``` + + + + + ## External documentation OpenApi allows a single reference to external documentation. This is a part of the top level `@OA\OpenApi`. diff --git a/docs/snippets/guide/cookbook/response_examples_an.php b/docs/snippets/guide/cookbook/response_examples_an.php new file mode 100644 index 000000000..24547dca5 --- /dev/null +++ b/docs/snippets/guide/cookbook/response_examples_an.php @@ -0,0 +1,22 @@ + true], summary: "An result object."), + new OA\Examples(example: "bool", value: false, summary: "A boolean value."), + ], + ), + )] + public function operation() + { + } +} From 5279f0eda37c1c3f0d03cf35952ce5e87dc73b2d Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Tue, 18 Feb 2025 23:54:54 +0900 Subject: [PATCH 05/44] external docs --- docs/guide/cookbook.md | 22 ++++++++++--------- .../cookbook/external_documentation_an.php | 13 +++++++++++ .../cookbook/external_documentation_at.php | 13 +++++++++++ 3 files changed, 38 insertions(+), 10 deletions(-) create mode 100644 docs/snippets/guide/cookbook/external_documentation_an.php create mode 100644 docs/snippets/guide/cookbook/external_documentation_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 06faab758..b98b4e329 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -36,16 +36,18 @@ support further grouping via the vendor extension `x-tagGroups`. ## External documentation OpenApi allows a single reference to external documentation. This is a part of the top level `@OA\OpenApi`. -```php -/** - * @OA\OpenApi( - * @OA\ExternalDocumentation( - * description="More documentation here...", - * url="https://example.com/externaldoc1/" - * ) - * ) - */ -``` + + + + ::: tip If no `@OA\OpenApi` is configured, `swagger-php` will create one automatically. diff --git a/docs/snippets/guide/cookbook/external_documentation_an.php b/docs/snippets/guide/cookbook/external_documentation_an.php new file mode 100644 index 000000000..8e5a8e8bc --- /dev/null +++ b/docs/snippets/guide/cookbook/external_documentation_an.php @@ -0,0 +1,13 @@ + Date: Wed, 19 Feb 2025 23:42:37 +0900 Subject: [PATCH 06/44] union types --- docs/guide/cookbook.md | 37 ++++++--------- .../properties_with_union_types_an.php | 27 +++++++++++ .../properties_with_union_types_at.php | 45 +++++++++++++++++++ 3 files changed, 85 insertions(+), 24 deletions(-) create mode 100644 docs/snippets/guide/cookbook/properties_with_union_types_an.php create mode 100644 docs/snippets/guide/cookbook/properties_with_union_types_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index b98b4e329..34760cb2b 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -67,30 +67,19 @@ That means the above example would also work with just the `OA\ExternalDocumenta ## Properties with union types Sometimes properties or even lists (arrays) may contain data of different types. This can be expressed using `oneOf`. -```php -/** - * @OA\Schema( - * schema="StringList", - * @OA\Property(property="value", type="array", @OA\Items(anyOf={@OA\Schema(type="string")})) - * ) - * @OA\Schema( - * schema="String", - * @OA\Property(property="value", type="string") - * ) - * @OA\Schema( - * schema="Object", - * @OA\Property(property="value", type="object") - * ) - * @OA\Schema( - * schema="mixedList", - * @OA\Property(property="fields", type="array", @OA\Items(oneOf={ - * @OA\Schema(ref="#/components/schemas/StringList"), - * @OA\Schema(ref="#/components/schemas/String"), - * @OA\Schema(ref="#/components/schemas/Object") - * })) - * ) - */ -``` + + + + + This will resolve into this YAML ```yaml diff --git a/docs/snippets/guide/cookbook/properties_with_union_types_an.php b/docs/snippets/guide/cookbook/properties_with_union_types_an.php new file mode 100644 index 000000000..93994ac8c --- /dev/null +++ b/docs/snippets/guide/cookbook/properties_with_union_types_an.php @@ -0,0 +1,27 @@ + Date: Sat, 22 Feb 2025 18:24:11 +0900 Subject: [PATCH 07/44] security schemes --- docs/guide/cookbook.md | 34 ++++++------------- .../guide/cookbook/security_schemas_an.php | 26 ++++++++++++++ .../guide/cookbook/security_schemas_at.php | 25 ++++++++++++++ 3 files changed, 62 insertions(+), 23 deletions(-) create mode 100644 docs/snippets/guide/cookbook/security_schemas_an.php create mode 100644 docs/snippets/guide/cookbook/security_schemas_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 34760cb2b..1f45d4b3c 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -123,30 +123,18 @@ components: ## Referencing a security scheme An API might have zero or more security schemes. These are defined at the top level and vary from simple to complex: -```php -/** - * @OA\SecurityScheme( - * type="apiKey", - * name="api_key", - * in="header", - * securityScheme="api_key" - * ) - * - * @OA\SecurityScheme( - * type="oauth2", - * securityScheme="petstore_auth", - * @OA\Flow( - * authorizationUrl="http://petstore.swagger.io/oauth/dialog", - * flow="implicit", - * scopes={ - * "read:pets": "read your pets", - * "write:pets": "modify pets in your account" - * } - * ) - * ) - */ -``` + + + + To declare an endpoint as secure and define what security schemes are available to authenticate a client it needs to be added to the operation, for example: diff --git a/docs/snippets/guide/cookbook/security_schemas_an.php b/docs/snippets/guide/cookbook/security_schemas_an.php new file mode 100644 index 000000000..c66edf61a --- /dev/null +++ b/docs/snippets/guide/cookbook/security_schemas_an.php @@ -0,0 +1,26 @@ + "read your pets", + "write:pets" => "modify pets in your account" + ], + ), +)] +class OpenApiSpec +{ +} From 6cf387fb20eeccaf654ac3ef112dfe87b267197b Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Sat, 22 Feb 2025 18:36:33 +0900 Subject: [PATCH 08/44] secure endpoint --- docs/guide/cookbook.md | 23 +++++++++++-------- .../guide/cookbook/secure_endpoint_an.php | 16 +++++++++++++ .../guide/cookbook/secure_endpoint_at.php | 20 ++++++++++++++++ 3 files changed, 49 insertions(+), 10 deletions(-) create mode 100644 docs/snippets/guide/cookbook/secure_endpoint_an.php create mode 100644 docs/snippets/guide/cookbook/secure_endpoint_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 1f45d4b3c..b9d67823c 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -138,16 +138,19 @@ An API might have zero or more security schemes. These are defined at the top le To declare an endpoint as secure and define what security schemes are available to authenticate a client it needs to be added to the operation, for example: -```php -/** - * @OA\Get( - * path="/api/secure/", - * summary="Requires authentication" - * ), - * security={ {"api_key": {}} } - * ) - */ -``` + + + + + ::: tip Endpoints can support multiple security schemes and have custom options too: ```php diff --git a/docs/snippets/guide/cookbook/secure_endpoint_an.php b/docs/snippets/guide/cookbook/secure_endpoint_an.php new file mode 100644 index 000000000..61546f973 --- /dev/null +++ b/docs/snippets/guide/cookbook/secure_endpoint_an.php @@ -0,0 +1,16 @@ + [], + ], + ], + )] + public function getSecurely() + { + // ... + } +} From e9c79c49d52c43f0bedee73af800060b76826dee Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Mon, 3 Mar 2025 23:38:13 +0900 Subject: [PATCH 09/44] multiple security schemes --- docs/guide/cookbook.md | 25 +++++++++---------- .../cookbook/security_schema_tips_an.php | 19 ++++++++++++++ .../cookbook/security_schema_tips_at.php | 18 +++++++++++++ 3 files changed, 49 insertions(+), 13 deletions(-) create mode 100644 docs/snippets/guide/cookbook/security_schema_tips_an.php create mode 100644 docs/snippets/guide/cookbook/security_schema_tips_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index b9d67823c..9f7d87ae6 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -153,19 +153,18 @@ added to the operation, for example: ::: tip Endpoints can support multiple security schemes and have custom options too: -```php -/** - * @OA\Get( - * path="/api/secure/", - * summary="Requires authentication" - * ), - * security={ - * { "api_key": {} }, - * { "petstore_auth": {"write:pets", "read:pets"} } - * } - * ) - */ -``` + + + + ::: ## File upload with headers diff --git a/docs/snippets/guide/cookbook/security_schema_tips_an.php b/docs/snippets/guide/cookbook/security_schema_tips_an.php new file mode 100644 index 000000000..c047998ad --- /dev/null +++ b/docs/snippets/guide/cookbook/security_schema_tips_an.php @@ -0,0 +1,19 @@ + []], + ['petstore_auth' => ['write:pets', 'read:pets']] + ] + )] + public function secure() + { + } +} From 7ac54629544da011853524268cace24046cad1c8 Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Fri, 28 Mar 2025 23:43:21 +0900 Subject: [PATCH 10/44] file upload --- docs/guide/cookbook.md | 46 ++++++------------- .../cookbook/file_upload_with_headers_an.php | 39 ++++++++++++++++ .../cookbook/file_upload_with_headers_at.php | 38 +++++++++++++++ 3 files changed, 91 insertions(+), 32 deletions(-) create mode 100644 docs/snippets/guide/cookbook/file_upload_with_headers_an.php create mode 100644 docs/snippets/guide/cookbook/file_upload_with_headers_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 9f7d87ae6..a8eafb2eb 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -168,38 +168,20 @@ added to the operation, for example: ::: ## File upload with headers -```php -/** - * @OA\Post( - * path="/v1/media/upload", - * summary="Upload document", - * description="", - * tags={"Media"}, - * @OA\RequestBody( - * required=true, - * @OA\MediaType( - * mediaType="application/octet-stream", - * @OA\Schema( - * required={"content"}, - * @OA\Property( - * description="Binary content of file", - * property="content", - * type="string", - * format="binary" - * ) - * ) - * ) - * ), - * @OA\Response( - * response=200, description="Success", - * @OA\Schema(type="string") - * ), - * @OA\Response( - * response=400, description="Bad Request" - * ) - * ) - */ -``` + + + + + + ## Set the XML root name The `OA\Xml` annotation may be used to set the XML root element for a given `@OA\XmlContent` response body diff --git a/docs/snippets/guide/cookbook/file_upload_with_headers_an.php b/docs/snippets/guide/cookbook/file_upload_with_headers_an.php new file mode 100644 index 000000000..346b28081 --- /dev/null +++ b/docs/snippets/guide/cookbook/file_upload_with_headers_an.php @@ -0,0 +1,39 @@ + Date: Tue, 15 Apr 2025 04:21:27 +0000 Subject: [PATCH 11/44] add success response description in attribute example --- docs/snippets/guide/cookbook/file_upload_with_headers_at.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/snippets/guide/cookbook/file_upload_with_headers_at.php b/docs/snippets/guide/cookbook/file_upload_with_headers_at.php index 0c540a612..5e6fcba6d 100644 --- a/docs/snippets/guide/cookbook/file_upload_with_headers_at.php +++ b/docs/snippets/guide/cookbook/file_upload_with_headers_at.php @@ -27,6 +27,10 @@ class Controller ), ), )] + #[OA\Response( + response: 200, + description: "Success", + )] #[OA\Response( response: 400, description: "Bad Request", From 9da2add62fed42291878f2c405be19a13e03cdcb Mon Sep 17 00:00:00 2001 From: natsuki ueda Date: Wed, 16 Apr 2025 19:31:53 +0900 Subject: [PATCH 12/44] xml content response --- docs/guide/cookbook.md | 32 +++++++------------ .../guide/cookbook/set_xml_root_name_an.php | 22 +++++++++++++ .../guide/cookbook/set_xml_root_name_at.php | 23 +++++++++++++ 3 files changed, 56 insertions(+), 21 deletions(-) create mode 100644 docs/snippets/guide/cookbook/set_xml_root_name_an.php create mode 100644 docs/snippets/guide/cookbook/set_xml_root_name_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index a8eafb2eb..e6280c416 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -186,28 +186,18 @@ added to the operation, for example: The `OA\Xml` annotation may be used to set the XML root element for a given `@OA\XmlContent` response body -```php -/** - * @OA\Schema( - * schema="Error", - * @OA\Property(property="message"), - * @OA\Xml(name="details") - * ) - */ + + + + ## upload multipart/form-data Form posts are `@OA\Post` requests with a `multipart/form-data` `@OA\RequestBody`. The relevant bit looks something like this diff --git a/docs/snippets/guide/cookbook/set_xml_root_name_an.php b/docs/snippets/guide/cookbook/set_xml_root_name_an.php new file mode 100644 index 000000000..fdab3c023 --- /dev/null +++ b/docs/snippets/guide/cookbook/set_xml_root_name_an.php @@ -0,0 +1,22 @@ + Date: Wed, 16 Apr 2025 19:48:48 +0900 Subject: [PATCH 13/44] upload multipart/form-data --- docs/guide/cookbook.md | 36 +++++++----------- .../uploading_multiple_formdata_an.php | 31 ++++++++++++++++ .../uploading_multiple_formdata_at.php | 37 +++++++++++++++++++ 3 files changed, 81 insertions(+), 23 deletions(-) create mode 100644 docs/snippets/guide/cookbook/uploading_multiple_formdata_an.php create mode 100644 docs/snippets/guide/cookbook/uploading_multiple_formdata_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index e6280c416..5509f9d43 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -201,29 +201,19 @@ The `OA\Xml` annotation may be used to set the XML root element for a given `@OA ## upload multipart/form-data Form posts are `@OA\Post` requests with a `multipart/form-data` `@OA\RequestBody`. The relevant bit looks something like this -```php -/** - * @OA\Post( - * path="/v1/user/update", - * summary="Form post", - * @OA\RequestBody( - * @OA\MediaType( - * mediaType="multipart/form-data", - * @OA\Schema( - * @OA\Property(property="name"), - * @OA\Property( - * description="file to upload", - * property="avatar", - * type="string", - * format="binary", - * ), - * ) - * ) - * ), - * @OA\Response(response=200, description="Success") - * ) - */ -``` + + + + + ## Default security scheme for all endpoints Unless specified each endpoint needs to declare what security schemes it supports. However, there is a way diff --git a/docs/snippets/guide/cookbook/uploading_multiple_formdata_an.php b/docs/snippets/guide/cookbook/uploading_multiple_formdata_an.php new file mode 100644 index 000000000..cf3b1615b --- /dev/null +++ b/docs/snippets/guide/cookbook/uploading_multiple_formdata_an.php @@ -0,0 +1,31 @@ + Date: Sat, 26 Apr 2025 00:15:46 +0900 Subject: [PATCH 14/44] nested structure with @OA\Property --- docs/guide/cookbook.md | 45 +++++-------------- .../guide/cookbook/nested_objects_an.php | 36 +++++++++++++++ .../guide/cookbook/nested_objects_at.php | 36 +++++++++++++++ 3 files changed, 84 insertions(+), 33 deletions(-) create mode 100644 docs/snippets/guide/cookbook/nested_objects_an.php create mode 100644 docs/snippets/guide/cookbook/nested_objects_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 5509f9d43..c7d60243e 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -236,40 +236,19 @@ This is done on the `@OA\OpenApi` annotation: ## Nested objects Complex, nested data structures are defined by nesting `@OA\Property` annotations inside others (with `type="object"`). -```php -/** - * @OA\Schema( - * schema="Profile", - * type="object", -* - * @OA\Property( - * property="Status", - * type="string", - * example="0" - * ), - * - * @OA\Property( - * property="Group", - * type="object", - * - * @OA\Property( - * property="ID", - * description="ID de grupo", - * type="number", - * example=-1 - * ), - * - * @OA\Property( - * property="Name", - * description="Nombre de grupo", - * type="string", - * example="Superadmin" - * ) - * ) - * ) - */ -``` + + + + ## Documenting union type response data using `oneOf` A response with either a single or a list of `QualificationHolder`'s. diff --git a/docs/snippets/guide/cookbook/nested_objects_an.php b/docs/snippets/guide/cookbook/nested_objects_an.php new file mode 100644 index 000000000..cdd50d813 --- /dev/null +++ b/docs/snippets/guide/cookbook/nested_objects_an.php @@ -0,0 +1,36 @@ + Date: Sat, 26 Apr 2025 00:29:04 +0900 Subject: [PATCH 15/44] expression of single or list by oneOf --- docs/guide/cookbook.md | 29 +++++++++---------- .../guide/cookbook/oneof_example_an.php | 23 +++++++++++++++ .../guide/cookbook/oneof_example_at.php | 23 +++++++++++++++ 3 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 docs/snippets/guide/cookbook/oneof_example_an.php create mode 100644 docs/snippets/guide/cookbook/oneof_example_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index c7d60243e..516137b0e 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -252,22 +252,19 @@ Complex, nested data structures are defined by nesting `@OA\Property` annotation ## Documenting union type response data using `oneOf` A response with either a single or a list of `QualificationHolder`'s. -```php -/** - * @OA\Response( - * response=200, - * @OA\JsonContent( - * oneOf={ - * @OA\Schema(ref="#/components/schemas/QualificationHolder"), - * @OA\Schema( - * type="array", - * @OA\Items(ref="#/components/schemas/QualificationHolder") - * ) - * } - * ) - * ) - */ -``` + + + + + ## Reusing responses Global responses are found under `/components/responses` and can be referenced/shared just like schema definitions (models) diff --git a/docs/snippets/guide/cookbook/oneof_example_an.php b/docs/snippets/guide/cookbook/oneof_example_an.php new file mode 100644 index 000000000..ef13b8445 --- /dev/null +++ b/docs/snippets/guide/cookbook/oneof_example_an.php @@ -0,0 +1,23 @@ + Date: Wed, 7 May 2025 02:31:46 +0000 Subject: [PATCH 16/44] reusing responses --- docs/guide/cookbook.md | 37 +++++-------------- .../guide/cookbook/reusing_response_an.php | 29 +++++++++++++++ .../guide/cookbook/reusing_response_at.php | 25 +++++++++++++ 3 files changed, 64 insertions(+), 27 deletions(-) create mode 100644 docs/snippets/guide/cookbook/reusing_response_an.php create mode 100644 docs/snippets/guide/cookbook/reusing_response_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 516137b0e..2e38ccd83 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -269,35 +269,18 @@ A response with either a single or a list of `QualificationHolder`'s. ## Reusing responses Global responses are found under `/components/responses` and can be referenced/shared just like schema definitions (models) -```php -/** - * @OA\Response( - * response="product", - * description="All information about a product", - * @OA\JsonContent(ref="#/components/schemas/Product") - * ) - */ -class ProductResponse {} + + + + ::: tip `response` parameter is always required Even if referencing a shared response definition, the `response` parameter is still required. diff --git a/docs/snippets/guide/cookbook/reusing_response_an.php b/docs/snippets/guide/cookbook/reusing_response_an.php new file mode 100644 index 000000000..606445e12 --- /dev/null +++ b/docs/snippets/guide/cookbook/reusing_response_an.php @@ -0,0 +1,29 @@ + Date: Wed, 7 May 2025 02:32:44 +0000 Subject: [PATCH 17/44] callbacks --- docs/guide/cookbook.md | 42 +++++++------------ docs/snippets/guide/cookbook/callbacks_an.php | 31 ++++++++++++++ docs/snippets/guide/cookbook/callbacks_at.php | 35 ++++++++++++++++ 3 files changed, 80 insertions(+), 28 deletions(-) create mode 100644 docs/snippets/guide/cookbook/callbacks_an.php create mode 100644 docs/snippets/guide/cookbook/callbacks_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 2e38ccd83..1299311e1 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -312,34 +312,20 @@ There are two scenarios where this can happen The API does include basic support for callbacks. However, this needs to be set up mostly manually. **Example** -```php -/** - * ... - * - * callbacks={ - * "onChange"={ - * "{$request.query.callbackUrl}"={ - * "post": { - * "requestBody": @OA\RequestBody( - * description="subscription payload", - * @OA\MediaType(mediaType="application/json", @OA\Schema( - * @OA\Property(property="timestamp", type="string", format="date-time", description="time of change") - * )) - * ) - * }, - * "responses": { - * "202": { - * "description": "Your server implementation should return this HTTP status code if the data was received successfully" - * } - * } - * } - * } - * } - * - * ... - * - */ -``` + + + + + + ## (Mostly) virtual models Typically, a model is annotated by adding a `@OA\Schema` annotation to the class and then individual `@OA\Property` annotations diff --git a/docs/snippets/guide/cookbook/callbacks_an.php b/docs/snippets/guide/cookbook/callbacks_an.php new file mode 100644 index 000000000..5e410a86c --- /dev/null +++ b/docs/snippets/guide/cookbook/callbacks_an.php @@ -0,0 +1,31 @@ + [ + '{$request.query.callbackUrl}' => [ + 'post' => [ + 'requestBody' => new OA\RequestBody( + description: 'subscription payload', + content: [ + new OA\MediaType( + mediaType: 'application/json', + schema: new OA\Schema( + properties: [ + new OA\Property( + property: 'timestamp', + type: 'string', + format: 'date-time', + description: 'time of change' + ), + ], + ), + ), + ], + ), + ], + ], + ], + ], + // ... +)] +class Controller {} From 8c166affaf687220d94dfc9b84b817644fca9c08 Mon Sep 17 00:00:00 2001 From: natsuki ueda <63272932+natsuki-engr@users.noreply.github.com> Date: Wed, 7 May 2025 02:34:00 +0000 Subject: [PATCH 18/44] virtual model --- docs/guide/cookbook.md | 22 ++++++++++--------- .../guide/cookbook/virtual_model_an.php | 17 ++++++++++++++ .../guide/cookbook/virtual_model_at.php | 11 ++++++++++ 3 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 docs/snippets/guide/cookbook/virtual_model_an.php create mode 100644 docs/snippets/guide/cookbook/virtual_model_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 1299311e1..12af29ef2 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -334,17 +334,19 @@ to the individually declared class properties. It is possible, however, to nest `O@\Property` annotations inside a schema even without properties. In fact, all that is needed is a code anchor - e.g. an empty class. -```php -use OpenApi\Attributes as OA; + + + + -#[OA\Schema( - properties: [ - 'name' => new OA\Property(property: 'name', type: 'string'), - 'email' => new OA\Property(property: 'email', type: 'string'), - ] -)] -class User {} -``` ## Using class name as type instead of references Typically, when referencing schemas this is done using `$ref`'s diff --git a/docs/snippets/guide/cookbook/virtual_model_an.php b/docs/snippets/guide/cookbook/virtual_model_an.php new file mode 100644 index 000000000..27a80a280 --- /dev/null +++ b/docs/snippets/guide/cookbook/virtual_model_an.php @@ -0,0 +1,17 @@ + new OA\Property(property: 'name', type: 'string'), + 'email' => new OA\Property(property: 'email', type: 'string'), + ] +)] +class User {} From b902bb896ea28f61f787b36bc3182d32b6fe2adf Mon Sep 17 00:00:00 2001 From: natsuki ueda <63272932+natsuki-engr@users.noreply.github.com> Date: Wed, 7 May 2025 02:41:00 +0000 Subject: [PATCH 19/44] class name as type --- docs/guide/cookbook.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 12af29ef2..240fa26cb 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -378,6 +378,9 @@ class name. With the same `User` schema as before, the `Book::author` property could be written in a few different ways + + + ```php #[OAT\Property()] public User author; @@ -396,10 +399,32 @@ With the same `User` schema as before, the `Book::author` property could be writ **or** ```php - #[OAT\Property(type: User::class)] + #[OA\Property(type: User::class)] public author; ``` + + + + +```php + /** @OA\Property() */ + public User author; +``` + +**or** + +```php + /** + * @var User + * @OA\Property() + */ + public author; +``` + + + + ## Enums As of PHP 8.1 there is native support for `enum`'s. From bf2837aa644486e3265773da561f04f88bcbfdd9 Mon Sep 17 00:00:00 2001 From: natsuki ueda <63272932+natsuki-engr@users.noreply.github.com> Date: Wed, 7 May 2025 02:45:48 +0000 Subject: [PATCH 20/44] enums --- docs/guide/cookbook.md | 25 ++++++++++------------- docs/snippets/guide/cookbook/enums_an.php | 18 ++++++++++++++++ docs/snippets/guide/cookbook/enums_at.php | 18 ++++++++++++++++ 3 files changed, 47 insertions(+), 14 deletions(-) create mode 100644 docs/snippets/guide/cookbook/enums_an.php create mode 100644 docs/snippets/guide/cookbook/enums_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 240fa26cb..d9e78bcbd 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -432,21 +432,18 @@ As of PHP 8.1 there is native support for `enum`'s. **Example** -```php -#[Schema()] -enum State -{ - case OPEN; - case MERGED; - case DECLINED; -} + + + + However, in this case the schema generated for `State` will be an enum: diff --git a/docs/snippets/guide/cookbook/enums_an.php b/docs/snippets/guide/cookbook/enums_an.php new file mode 100644 index 000000000..b99aaeb8b --- /dev/null +++ b/docs/snippets/guide/cookbook/enums_an.php @@ -0,0 +1,18 @@ + Date: Wed, 7 May 2025 02:50:47 +0000 Subject: [PATCH 21/44] multi value query parameter --- docs/guide/cookbook.md | 34 +++++++------------ .../multi_value_query_parameter_an.php | 30 ++++++++++++++++ .../multi_value_query_parameter_at.php | 32 +++++++++++++++++ 3 files changed, 75 insertions(+), 21 deletions(-) create mode 100644 docs/snippets/guide/cookbook/multi_value_query_parameter_an.php create mode 100644 docs/snippets/guide/cookbook/multi_value_query_parameter_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index d9e78bcbd..674b44e0d 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -470,27 +470,19 @@ name uses trailing `[]`. In fact, it is possible to create nested arrays too by In terms of OpenAPI, the parameters can be considered a single parameter with a list of values. -```php -/** - * @OA\Get( - * path="/api/endpoint", - * description="The endpoint", - * operationId="endpoint", - * tags={"endpoints"}, - * @OA\Parameter( - * name="things[]", - * in="query", - * description="A list of things.", - * required=false, - * @OA\Schema( - * type="array", - * @OA\Items(type="integer") - * ) - * ), - * @OA\Response(response="200", description="All good") - * ) - */ -``` + + + + + The corresponding bit of the spec will look like this: diff --git a/docs/snippets/guide/cookbook/multi_value_query_parameter_an.php b/docs/snippets/guide/cookbook/multi_value_query_parameter_an.php new file mode 100644 index 000000000..1c812517b --- /dev/null +++ b/docs/snippets/guide/cookbook/multi_value_query_parameter_an.php @@ -0,0 +1,30 @@ + Date: Wed, 7 May 2025 02:52:15 +0000 Subject: [PATCH 22/44] custom response classes --- docs/guide/cookbook.md | 43 ++++--------------- .../cookbook/custom_response_classes_an.php | 42 ++++++++++++++++++ .../cookbook/custom_response_classes_at.php | 29 +++++++++++++ 3 files changed, 79 insertions(+), 35 deletions(-) create mode 100644 docs/snippets/guide/cookbook/custom_response_classes_an.php create mode 100644 docs/snippets/guide/cookbook/custom_response_classes_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index 674b44e0d..b1754c700 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -511,46 +511,19 @@ The beauty is that in your custom `__construct()` method you can prefill as much Best of all, this works for both annotations and attributes. Example: -```php -use OpenApi\Attributes as OA; -/** - * @Annotation - */ -#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)] -class BadRequest extends OA\Response -{ - public function __construct() - { - parent::__construct(response: 400, description: 'Bad request'); - } -} + + + + ::: tip Annotations only? If you are only interested in annotations you canleave out the attribute setup line (`#[\Attribute...`) for `BadRequest`. diff --git a/docs/snippets/guide/cookbook/custom_response_classes_an.php b/docs/snippets/guide/cookbook/custom_response_classes_an.php new file mode 100644 index 000000000..6a01b736b --- /dev/null +++ b/docs/snippets/guide/cookbook/custom_response_classes_an.php @@ -0,0 +1,42 @@ + Date: Wed, 7 May 2025 02:53:27 +0000 Subject: [PATCH 23/44] class constants --- docs/guide/cookbook.md | 22 +++++++++++-------- .../guide/cookbook/class_constants_an.php | 12 ++++++++++ .../guide/cookbook/class_constants_at.php | 10 +++++++++ 3 files changed, 35 insertions(+), 9 deletions(-) create mode 100644 docs/snippets/guide/cookbook/class_constants_an.php create mode 100644 docs/snippets/guide/cookbook/class_constants_at.php diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index b1754c700..d775d5719 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -532,16 +532,20 @@ Furthermore, your custom annotations should extend from the `OpenApi\Annotations ::: ## Annotating class constants -```php -use OpenApi\Attributes as OA; -#[OA\Schema()] -class Airport -{ - #[OA\Property(property='kind')] - public const KIND = 'Airport'; -} -``` + + + + + The `const` property is supported in OpenApi 3.1.0. ```yaml components: diff --git a/docs/snippets/guide/cookbook/class_constants_an.php b/docs/snippets/guide/cookbook/class_constants_an.php new file mode 100644 index 000000000..5f5c7f487 --- /dev/null +++ b/docs/snippets/guide/cookbook/class_constants_an.php @@ -0,0 +1,12 @@ + Date: Wed, 7 May 2025 12:47:36 +0900 Subject: [PATCH 24/44] fix wrong id Co-authored-by: Martin Rademacher --- docs/guide/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/cookbook.md b/docs/guide/cookbook.md index d775d5719..01c2fb1ae 100644 --- a/docs/guide/cookbook.md +++ b/docs/guide/cookbook.md @@ -202,7 +202,7 @@ The `OA\Xml` annotation may be used to set the XML root element for a given `@OA ## upload multipart/form-data Form posts are `@OA\Post` requests with a `multipart/form-data` `@OA\RequestBody`. The relevant bit looks something like this - +