From a3bfbf2dc56d7f9630a586d554c998a5a196d3c3 Mon Sep 17 00:00:00 2001 From: Martin Rademacher Date: Fri, 11 Feb 2022 13:12:30 +1300 Subject: [PATCH] Fix example YAML validation warnings (#1114) --- Examples/example-object/example-object.php | 18 ++++++- Examples/example-object/example-object.yaml | 19 +++++++ Examples/misc/misc-api.php | 37 +++++++++++++- Examples/misc/misc.yaml | 32 ++++++++++++ Examples/nesting/ApiController.php | 18 ++++++- Examples/nesting/nesting.yaml | 15 +++++- Examples/polymorphism/Controller.php | 22 ++++++-- Examples/polymorphism/polymorphism.yaml | 33 ++++++++---- .../petstore-simple/SimplePetsController.php | 4 ++ Examples/swagger-spec/petstore-simple/api.php | 4 ++ .../petstore-simple-3.1.0.yaml | 12 +++++ .../petstore-simple/petstore-simple.yaml | 12 +++++ .../controllers/PetWithDocsController.php | 4 ++ .../petstore-with-external-docs/docs.php | 4 ++ .../petstore-with-external-docs.yaml | 12 +++++ .../{Pet.php => GreenProduct.php} | 2 +- .../using-interfaces/ProductController.php | 30 ++++++++++- Examples/using-interfaces/api-spec.php | 12 ++++- .../using-interfaces/using-interfaces.yaml | 51 ++++++++++++++++--- composer.json | 2 +- tests/ExamplesTest.php | 6 +++ 21 files changed, 318 insertions(+), 31 deletions(-) rename Examples/using-interfaces/{Pet.php => GreenProduct.php} (75%) diff --git a/Examples/example-object/example-object.php b/Examples/example-object/example-object.php index e48b9bb59..65301417b 100644 --- a/Examples/example-object/example-object.php +++ b/Examples/example-object/example-object.php @@ -5,9 +5,19 @@ use OpenApi\Annotations as OA; /** + * @OA\Tag( + * name="user", + * description="User related operations" + * ) * @OA\Info( * version="1.0", - * title="Example for response examples value" + * title="Example for response examples value", + * description="Example info", + * @OA\Contact(name="Swagger API Team") + * ) + * @OA\Server( + * url="https://example.localhost", + * description="API server" * ) */ class OpenApiSpec @@ -18,6 +28,9 @@ class OpenApiSpec * @OA\Put( * path="/users/{id}", * summary="Updates a user", + * description="Updates a user", + * operationId="updateUser", + * tags={"user"}, * @OA\Parameter( * description="Parameter with mutliple examples", * in="path", @@ -41,6 +54,9 @@ class UserUpdateEndpoint * @OA\Post( * path="/users", * summary="Adds a new user - with oneOf examples", + * description="Adds a new user", + * operationId="addUser", + * tags={"user"}, * @OA\RequestBody( * @OA\MediaType( * mediaType="application/json", diff --git a/Examples/example-object/example-object.yaml b/Examples/example-object/example-object.yaml index 50ee72609..2afd0e2a9 100644 --- a/Examples/example-object/example-object.yaml +++ b/Examples/example-object/example-object.yaml @@ -1,11 +1,22 @@ openapi: 3.0.0 info: title: 'Example for response examples value' + description: 'Example info' + contact: + name: 'Swagger API Team' version: '1.0' +servers: + - + url: 'https://example.localhost' + description: 'API server' paths: '/users/{id}': put: + tags: + - user summary: 'Updates a user' + description: 'Updates a user' + operationId: updateUser parameters: - name: id @@ -26,7 +37,11 @@ paths: description: OK /users: post: + tags: + - user summary: 'Adds a new user - with oneOf examples' + description: 'Adds a new user' + operationId: addUser requestBody: content: application/json: @@ -69,3 +84,7 @@ components: error: type: string type: object +tags: + - + name: user + description: 'User related operations' diff --git a/Examples/misc/misc-api.php b/Examples/misc/misc-api.php index a42fc6696..00a386582 100644 --- a/Examples/misc/misc-api.php +++ b/Examples/misc/misc-api.php @@ -4,14 +4,18 @@ /** * @OA\OpenApi( - * security={{"bearerAuth": {}}} + * security={{"bearerAuth": {}}}, + * @OA\Tag( + * name="endpoints" + * ) * ) * * @OA\Info( * title="Testing annotations from bugreports", * version="1.0.0", * description="NOTE: -This sentence is on a new line" +This sentence is on a new line", + * @OA\Contact(name="Swagger API Team") * ) * * @OA\Components( @@ -42,6 +46,9 @@ class OpenApiSpec * * @OA\Get( * path="/api/endpoint", + * description="An endpoint", + * operationId="endpoint", + * tags={"endpoints"}, * @OA\Parameter(name="filter", in="query", @OA\JsonContent( * @OA\Property(property="type", type="string"), * @OA\Property(property="color", type="string"), @@ -72,3 +79,29 @@ class Endpoint class Response { } + +/** + * Another API endpoint. + * + * @OA\Get( + * path="/api/anotherendpoint", + * description="Another endpoint", + * operationId="anotherendpoints", + * tags={"endpoints"}, + * @OA\Parameter( + * name="things[]", + * in="query", + * description="A list of things.", + * required=false, + * @OA\Schema( + * type="array", + * @OA\Items(type="integer") + * ) + * ), + * security={{ "bearerAuth": {} }}, + * @OA\Response(response="200", ref="#/components/responses/200") + * ) + */ +class MultiValueQueryParam +{ +} diff --git a/Examples/misc/misc.yaml b/Examples/misc/misc.yaml index 3508ba63e..d3641733f 100644 --- a/Examples/misc/misc.yaml +++ b/Examples/misc/misc.yaml @@ -2,6 +2,8 @@ openapi: 3.0.0 info: title: 'Testing annotations from bugreports' description: "NOTE:\nThis sentence is on a new line" + contact: + name: 'Swagger API Team' version: 1.0.0 servers: - @@ -16,7 +18,11 @@ servers: paths: /api/endpoint: get: + tags: + - endpoints summary: 'An API endpoint.' + description: 'An endpoint' + operationId: endpoint parameters: - name: filter @@ -34,6 +40,29 @@ paths: security: - bearerAuth: [] + /api/anotherendpoint: + get: + tags: + - endpoints + summary: 'Another API endpoint.' + description: 'Another endpoint' + operationId: anotherendpoints + parameters: + - + name: 'things[]' + in: query + description: 'A list of things.' + required: false + schema: + type: array + items: + type: integer + responses: + '200': + $ref: '#/components/responses/200' + security: + - + bearerAuth: [] components: responses: '200': @@ -66,3 +95,6 @@ components: security: - bearerAuth: [] +tags: + - + name: endpoints diff --git a/Examples/nesting/ApiController.php b/Examples/nesting/ApiController.php index 7319ef42f..02f3fe4e0 100644 --- a/Examples/nesting/ApiController.php +++ b/Examples/nesting/ApiController.php @@ -5,7 +5,20 @@ /** * An entity controller class. * - * @OA\Info(version="1.0.0", title="Nested schemas") + * @OA\Info( + * version="1.0.0", + * title="Nested schemas", + * description="Example info", + * @OA\Contact(name="Swagger API Team") + * ) + * @OA\Server( + * url="https://example.localhost", + * description="API server" + * ) + * @OA\Tag( + * name="api", + * description="All API endpoints" + * ) */ class ApiController { @@ -13,6 +26,7 @@ class ApiController * @OA\Get( * tags={"api"}, * path="/entity/{id}", + * description="Get the entity", * @OA\Parameter( * name="id", * in="path", @@ -23,7 +37,7 @@ class ApiController * ) * ), * @OA\Response( - * response="default", + * response="200", * description="successful operation", * @OA\JsonContent(ref="#/components/schemas/ActualModel") * ) diff --git a/Examples/nesting/nesting.yaml b/Examples/nesting/nesting.yaml index d32cd70dd..2f33b6c01 100644 --- a/Examples/nesting/nesting.yaml +++ b/Examples/nesting/nesting.yaml @@ -1,13 +1,20 @@ openapi: 3.0.0 info: title: 'Nested schemas' - description: 'An entity controller class.' + description: 'Example info' + contact: + name: 'Swagger API Team' version: 1.0.0 +servers: + - + url: 'https://example.localhost' + description: 'API server' paths: '/entity/{id}': get: tags: - api + description: 'Get the entity' operationId: dd148eadcee53770e24b2350f932e3bd parameters: - @@ -18,7 +25,7 @@ paths: type: integer format: int64 responses: - default: + '200': description: 'successful operation' content: application/json: @@ -53,3 +60,7 @@ components: base: type: string type: object +tags: + - + name: api + description: 'All API endpoints' diff --git a/Examples/polymorphism/Controller.php b/Examples/polymorphism/Controller.php index 5a77d9c86..914ef3c9a 100644 --- a/Examples/polymorphism/Controller.php +++ b/Examples/polymorphism/Controller.php @@ -4,15 +4,31 @@ use OpenApi\Annotations as OA; +/** + * @OA\Info( + * title="Polymorphism", + * description="Polymorphism example", + * version="1", + * @OA\Contact(name="Swagger API Team") + * ) + * @OA\Tag( + * name="api", + * description="API operations" + * ) + * @OA\Server( + * url="https://example.localhost", + * description="API server" + * ) + */ class Controller { /** - * @OA\Info(title="Polymorphism", version="1") - * * @OA\Get( * path="/test", + * description="Get test", + * tags={"api"}, * @OA\Response( - * response="default", + * response="200", * description="Polymorphism", * @OA\JsonContent(ref="#/components/schemas/Request") * ) diff --git a/Examples/polymorphism/polymorphism.yaml b/Examples/polymorphism/polymorphism.yaml index 3dc62900f..9d903f34b 100644 --- a/Examples/polymorphism/polymorphism.yaml +++ b/Examples/polymorphism/polymorphism.yaml @@ -1,13 +1,23 @@ openapi: 3.0.0 info: title: Polymorphism + description: 'Polymorphism example' + contact: + name: 'Swagger API Team' version: '1' +servers: + - + url: 'https://example.localhost' + description: 'API server' paths: /test: get: - operationId: ef7f8a05d4ce52bae215869c1decc7c1 + tags: + - api + description: 'Get test' + operationId: 2bf08e1a95c02130edf82da5846bfca3 responses: - default: + '200': description: Polymorphism content: application/json: @@ -18,12 +28,12 @@ components: Responsible: properties: type: - nullable: false type: string enum: - employee - assignee - fl + nullable: false type: object discriminator: propertyName: type @@ -37,25 +47,28 @@ components: $ref: '#/components/schemas/EmployeeResponsible' EmployeeResponsible: allOf: + - + $ref: '#/components/schemas/Responsible' - properties: property2: - nullable: false type: string - - - $ref: '#/components/schemas/Responsible' + nullable: false FlResponsible: allOf: + - + $ref: '#/components/schemas/Responsible' - properties: property3: - nullable: false type: string - - - $ref: '#/components/schemas/Responsible' + nullable: false Request: properties: payload: $ref: '#/components/schemas/Responsible' type: object - +tags: + - + name: api + description: 'API operations' diff --git a/Examples/swagger-spec/petstore-simple/SimplePetsController.php b/Examples/swagger-spec/petstore-simple/SimplePetsController.php index aa0742e62..2e0e6f5ff 100644 --- a/Examples/swagger-spec/petstore-simple/SimplePetsController.php +++ b/Examples/swagger-spec/petstore-simple/SimplePetsController.php @@ -9,6 +9,7 @@ class SimplePetsController * path="/pets", * description="Returns all pets from the system that the user has access to", * operationId="findPets", + * tags={"store"}, * @OA\Parameter( * name="tags", * in="query", @@ -81,6 +82,7 @@ public function findPets() * path="/pets/{id}", * description="Returns a user based on a single ID, if the user does not have access to the pet", * operationId="findPetById", + * tags={"store"}, * @OA\Parameter( * description="ID of pet to fetch", * in="path", @@ -136,6 +138,7 @@ public function findPetById() * path="/pets", * operationId="addPet", * description="Creates a new pet in the store. Duplicates are allowed", + * tags={"store"}, * @OA\RequestBody( * description="Pet to add to the store", * required=true, @@ -165,6 +168,7 @@ public function addPet() * path="/pets/{id}", * description="deletes a single pet based on the ID supplied", * operationId="deletePet", + * tags={"store"}, * @OA\Parameter( * description="ID of pet to delete", * in="path", diff --git a/Examples/swagger-spec/petstore-simple/api.php b/Examples/swagger-spec/petstore-simple/api.php index 91e389962..8fa6f9bcd 100644 --- a/Examples/swagger-spec/petstore-simple/api.php +++ b/Examples/swagger-spec/petstore-simple/api.php @@ -17,6 +17,10 @@ * @OA\License(name="MIT", identifier="MIT") * ), * ) + * @OA\Tag( + * name="store", + * description="The Pet Store" + * ) */ class OpenApiSpec { diff --git a/Examples/swagger-spec/petstore-simple/petstore-simple-3.1.0.yaml b/Examples/swagger-spec/petstore-simple/petstore-simple-3.1.0.yaml index 83036c16b..dd13c4234 100644 --- a/Examples/swagger-spec/petstore-simple/petstore-simple-3.1.0.yaml +++ b/Examples/swagger-spec/petstore-simple/petstore-simple-3.1.0.yaml @@ -16,6 +16,8 @@ servers: paths: /pets: get: + tags: + - store description: 'Returns all pets from the system that the user has access to' operationId: findPets parameters: @@ -77,6 +79,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' post: + tags: + - store description: 'Creates a new pet in the store. Duplicates are allowed' operationId: addPet requestBody: @@ -101,6 +105,8 @@ paths: $ref: '#/components/schemas/ErrorModel' '/pets/{id}': get: + tags: + - store description: 'Returns a user based on a single ID, if the user does not have access to the pet' operationId: findPetById parameters: @@ -144,6 +150,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' delete: + tags: + - store description: 'deletes a single pet based on the ID supplied' operationId: deletePet parameters: @@ -195,3 +203,7 @@ components: message: type: string type: object +tags: + - + name: store + description: 'The Pet Store' diff --git a/Examples/swagger-spec/petstore-simple/petstore-simple.yaml b/Examples/swagger-spec/petstore-simple/petstore-simple.yaml index 08edfe036..22541b1c8 100644 --- a/Examples/swagger-spec/petstore-simple/petstore-simple.yaml +++ b/Examples/swagger-spec/petstore-simple/petstore-simple.yaml @@ -15,6 +15,8 @@ servers: paths: /pets: get: + tags: + - store description: 'Returns all pets from the system that the user has access to' operationId: findPets parameters: @@ -76,6 +78,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' post: + tags: + - store description: 'Creates a new pet in the store. Duplicates are allowed' operationId: addPet requestBody: @@ -100,6 +104,8 @@ paths: $ref: '#/components/schemas/ErrorModel' '/pets/{id}': get: + tags: + - store description: 'Returns a user based on a single ID, if the user does not have access to the pet' operationId: findPetById parameters: @@ -143,6 +149,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' delete: + tags: + - store description: 'deletes a single pet based on the ID supplied' operationId: deletePet parameters: @@ -194,3 +202,7 @@ components: message: type: string type: object +tags: + - + name: store + description: 'The Pet Store' diff --git a/Examples/swagger-spec/petstore-with-external-docs/controllers/PetWithDocsController.php b/Examples/swagger-spec/petstore-with-external-docs/controllers/PetWithDocsController.php index e15a27dae..45dc3471c 100644 --- a/Examples/swagger-spec/petstore-with-external-docs/controllers/PetWithDocsController.php +++ b/Examples/swagger-spec/petstore-with-external-docs/controllers/PetWithDocsController.php @@ -7,6 +7,7 @@ class PetWithDocsController * path="/pets", * operationId="addPet", * description="Creates a new pet in the store. Duplicates are allowed", + * tags={"store"}, * @OA\RequestBody( * description="Pet to add to the store", * required=true, @@ -33,6 +34,7 @@ public function addPet() * path="/pets/{id}", * description="Returns a user based on a single ID, if the user does not have access to the pet", * operationId="findPetById", + * tags={"store"}, * @OA\Parameter( * description="ID of pet to fetch", * in="path", @@ -82,6 +84,7 @@ public function findPetById() * path="/pets", * description="Returns all pets from the system that the user has access to", * operationId="findPets", + * tags={"store"}, * @OA\Parameter( * name="tags", * in="query", @@ -164,6 +167,7 @@ public function findPets() * path="/pets/{id}", * description="deletes a single pet based on the ID supplied", * operationId="deletePet", + * tags={"store"}, * @OA\Parameter( * description="ID of pet to delete", * in="path", diff --git a/Examples/swagger-spec/petstore-with-external-docs/docs.php b/Examples/swagger-spec/petstore-with-external-docs/docs.php index 813a7948d..494614d55 100644 --- a/Examples/swagger-spec/petstore-with-external-docs/docs.php +++ b/Examples/swagger-spec/petstore-with-external-docs/docs.php @@ -26,6 +26,10 @@ * url="https://swagger.io/about" * ) * ) + * @OA\Tag( + * name="store", + * description="The Pet Store" + * ) */ class OpenApiSpec { diff --git a/Examples/swagger-spec/petstore-with-external-docs/petstore-with-external-docs.yaml b/Examples/swagger-spec/petstore-with-external-docs/petstore-with-external-docs.yaml index add65cbdd..0dfe0a5c2 100644 --- a/Examples/swagger-spec/petstore-with-external-docs/petstore-with-external-docs.yaml +++ b/Examples/swagger-spec/petstore-with-external-docs/petstore-with-external-docs.yaml @@ -18,6 +18,8 @@ servers: paths: /pets: get: + tags: + - store description: 'Returns all pets from the system that the user has access to' externalDocs: description: 'find more info here' @@ -82,6 +84,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' post: + tags: + - store description: 'Creates a new pet in the store. Duplicates are allowed' operationId: addPet requestBody: @@ -106,6 +110,8 @@ paths: $ref: '#/components/schemas/ErrorModel' '/pets/{id}': get: + tags: + - store description: 'Returns a user based on a single ID, if the user does not have access to the pet' operationId: findPetById parameters: @@ -149,6 +155,8 @@ paths: schema: $ref: '#/components/schemas/ErrorModel' delete: + tags: + - store description: 'deletes a single pet based on the ID supplied' operationId: deletePet parameters: @@ -200,6 +208,10 @@ components: type: integer format: int64 type: object +tags: + - + name: store + description: 'The Pet Store' externalDocs: description: 'find more info here' url: 'https://swagger.io/about' diff --git a/Examples/using-interfaces/Pet.php b/Examples/using-interfaces/GreenProduct.php similarity index 75% rename from Examples/using-interfaces/Pet.php rename to Examples/using-interfaces/GreenProduct.php index 6d09ba450..ab48ead8c 100644 --- a/Examples/using-interfaces/Pet.php +++ b/Examples/using-interfaces/GreenProduct.php @@ -5,7 +5,7 @@ /** * @OA\Schema(title="Pet") */ -class Pet implements ColorInterface +class GreenProduct extends Product implements ColorInterface { /** * @inheritDoc diff --git a/Examples/using-interfaces/ProductController.php b/Examples/using-interfaces/ProductController.php index 495b67c1f..7aaa17087 100644 --- a/Examples/using-interfaces/ProductController.php +++ b/Examples/using-interfaces/ProductController.php @@ -8,6 +8,8 @@ class ProductController * @OA\Get( * tags={"Products"}, * path="/products/{id}", + * description="Get product in any colour for id", + * tags={"api"}, * @OA\Parameter( * description="ID of product to return", * in="path", @@ -18,7 +20,7 @@ class ProductController * ) * ), * @OA\Response( - * response="default", + * response="200", * description="successful operation", * @OA\JsonContent(ref="#/components/schemas/Product") * ) @@ -27,4 +29,30 @@ class ProductController public function getProduct($id) { } + + /** + * @OA\Get( + * tags={"Products"}, + * path="/products/green/{id}", + * description="Get green products", + * tags={"api"}, + * @OA\Parameter( + * description="ID of product to return", + * in="path", + * name="id", + * required=true, + * @OA\Schema( + * type="string" + * ) + * ), + * @OA\Response( + * response="200", + * description="successful operation", + * @OA\JsonContent(ref="#/components/schemas/GreenProduct") + * ) + * ) + */ + public function getGreenProduct($id) + { + } } diff --git a/Examples/using-interfaces/api-spec.php b/Examples/using-interfaces/api-spec.php index 152fa467d..df57ddcfc 100644 --- a/Examples/using-interfaces/api-spec.php +++ b/Examples/using-interfaces/api-spec.php @@ -11,7 +11,17 @@ /** * @OA\Info( * version="1.0.0", - * title="Example of using interfaces in swagger-php" + * title="Example of using interfaces in swagger-php", + * description="Using interfaces", + * @OA\Contact(name="Swagger API Team") + * ) + * @OA\Server( + * url="https://example.localhost", + * description="API server" + * ) + * @OA\Tag( + * name="api", + * description="API operations" * ) */ class OpenApiSpec diff --git a/Examples/using-interfaces/using-interfaces.yaml b/Examples/using-interfaces/using-interfaces.yaml index 8400f7baa..ae8397650 100644 --- a/Examples/using-interfaces/using-interfaces.yaml +++ b/Examples/using-interfaces/using-interfaces.yaml @@ -1,12 +1,20 @@ openapi: 3.0.0 info: title: 'Example of using interfaces in swagger-php' + description: 'Using interfaces' + contact: + name: 'Swagger API Team' version: 1.0.0 +servers: + - + url: 'https://example.localhost' + description: 'API server' paths: '/products/{id}': get: tags: - - Products + - api + description: 'Get product in any colour for id' operationId: fef5577fd78858297fd2e4291598d8d0 parameters: - @@ -17,21 +25,46 @@ paths: schema: type: string responses: - default: + '200': description: 'successful operation' content: application/json: schema: $ref: '#/components/schemas/Product' + '/products/green/{id}': + get: + tags: + - api + description: 'Get green products' + operationId: d6617b71407f39c923d01fe82bb4ed65 + parameters: + - + name: id + in: path + description: 'ID of product to return' + required: true + schema: + type: string + responses: + '200': + description: 'successful operation' + content: + application/json: + schema: + $ref: '#/components/schemas/GreenProduct' components: schemas: - Pet: + GreenProduct: title: Pet - properties: - color: - description: 'The product color.' - example: blue type: object + allOf: + - + $ref: '#/components/schemas/Product' + - + properties: + color: + description: 'The product color.' + example: blue Product: title: 'Product model' type: object @@ -54,3 +87,7 @@ components: description: 'The product name.' example: toaster type: object +tags: + - + name: api + description: 'API operations' diff --git a/composer.json b/composer.json index 7fecc1f4e..00a938bfb 100644 --- a/composer.json +++ b/composer.json @@ -82,7 +82,7 @@ "phpstan analyse --memory-limit=2G", "psalm --show-info=true" ], - "spectral": "for ff in `find Examples -name *.yaml`; do spectral lint $ff; done", + "spectral": "for ff in `find Examples -name '*.yaml'`; do spectral lint $ff; done", "docs:dev": "cd docs && npm run dev", "docs:build": "cd docs && npm run build", "docs:deploy": "cd docs && npm run deploy" diff --git a/tests/ExamplesTest.php b/tests/ExamplesTest.php index adc74fc7f..128b6c78d 100644 --- a/tests/ExamplesTest.php +++ b/tests/ExamplesTest.php @@ -79,6 +79,12 @@ public function exampleMappings() 'petstore-with-external-docs.yaml', [], ], + 'polymorphism' => [ + OpenApi::VERSION_3_0_0, + 'polymorphism', + 'polymorphism.yaml', + [], + ], 'using-interfaces' => [ OpenApi::VERSION_3_0_0, 'using-interfaces',