Fix example YAML validation warnings (#1114)

zircote · Feb 11, 2022 · a3bfbf2 · a3bfbf2
1 parent 600beb4
commit a3bfbf2
Show file tree

Hide file tree

Showing 21 changed files with 318 additions and 31 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -5,14 +5,28 @@
 /**
  * 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
 {
     /**
      * @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
@@ -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
@@ -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
@@ -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'