swagger-blocks 2.0.2 → 3.0.0

data/lib/swagger/blocks/nodes/link_node.rb

@@ -0,0 +1,11 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class LinkNode < Node
+        def parameters(inline_keys = nil, &block)
+          self.data[:parameters] ||= Swagger::Blocks::Nodes::LinkParameterNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/link_parameter_node.rb

@@ -0,0 +1,8 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class LinkParameterNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/one_of_node.rb

@@ -0,0 +1,11 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class OneOfNode < Node
+        def items(inline_keys = nil, &block)
+          self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/operation_node.rb

@@ -24,6 +24,21 @@ module Swagger
           self.data[:security] ||= []
           self.data[:security] << Swagger::Blocks::Nodes::SecurityRequirementNode.call(version: version, inline_keys: inline_keys, &block)
         end
+
+        def request_body(inline_keys = nil, &block)
+          self.data[:requestBody] = Swagger::Blocks::Nodes::RequestBodyNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def callback(event_name, inline_keys = nil, &block)
+          self.data[:callbacks] ||= {}
+          self.data[:callbacks][event_name] = Swagger::Blocks::Nodes::CallbackNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def server(inline_keys = nil, &block)
+          raise NotSupportedError unless is_openapi_3_0?
+          self.data[:servers] ||= []
+          self.data[:servers] << Swagger::Blocks::Nodes::ServerNode.call(version: version, inline_keys: inline_keys, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/parameter_node.rb

@@ -10,6 +10,11 @@ module Swagger
         def items(inline_keys = nil, &block)
           self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
         end
+
+        def example(name, inline_keys = nil, &block)
+          self.data[:examples] ||= {}
+          self.data[:examples][name] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/path_node.rb

@@ -18,6 +18,12 @@ module Swagger
           self.data[:parameters] ||= []
           self.data[:parameters] << Swagger::Blocks::Nodes::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
         end
+
+        def server(inline_keys = nil, &block)
+          raise NotSupportedError unless is_openapi_3_0?
+          self.data[:servers] ||= []
+          self.data[:servers] << Swagger::Blocks::Nodes::ServerNode.call(version: version, inline_keys: inline_keys, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/property_node.rb

@@ -11,6 +11,11 @@ module Swagger
           self.data[:properties].version = version
           self.data[:properties].property(name, inline_keys, &block)
         end
+
+        def one_of(&block)
+          self.data[:oneOf] ||= []
+          self.data[:oneOf] << Swagger::Blocks::Nodes::OneOfNode.call(version: version, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/request_body_node.rb

@@ -0,0 +1,12 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class RequestBodyNode < Node
+        def content(type, inline_keys = nil, &block)
+          self.data[:content] ||= {}
+          self.data[:content][type] = Swagger::Blocks::Nodes::ContentNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/response_node.rb

@@ -13,10 +13,23 @@ module Swagger
           self.data[:headers][head] = Swagger::Blocks::Nodes::HeaderNode.call(version: version, inline_keys: inline_keys, &block)
         end
 
-        def example(exam, inline_keys = nil, &block)
-          # TODO validate 'exam' is as per spec
-          self.data[:examples] ||= {}
-          self.data[:examples][exam] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+        def content(type, inline_keys = nil, &block)
+          self.data[:content] ||= {}
+          self.data[:content][type] = Swagger::Blocks::Nodes::ContentNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def example(name = nil, inline_keys = nil, &block)
+          if name.nil?
+            self.data[:example] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+          else
+            self.data[:examples] ||= {}
+            self.data[:examples][name] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+          end
+        end
+
+        def link(name, inline_keys = nil, &block)
+          self.data[:links] ||= {}
+          self.data[:links][name] = Swagger::Blocks::Nodes::LinkNode.call(version: version, inline_keys: inline_keys, &block)
         end
       end
     end

data/lib/swagger/blocks/nodes/root_node.rb

@@ -31,7 +31,7 @@ module Swagger
         end
 
         def security(inline_keys = nil, &block)
-          raise NotSupportedError unless is_swagger_2_0?
+          raise NotSupportedError unless is_swagger_2_0? || is_openapi_3_0?
 
           self.data[:security] ||= []
           self.data[:security] << Swagger::Blocks::Nodes::SecurityRequirementNode.call(version: version, inline_keys: inline_keys, &block)
@@ -42,12 +42,26 @@ module Swagger
         end
 
         def tag(inline_keys = nil, &block)
-          raise NotSupportedError unless is_swagger_2_0?
+          raise NotSupportedError unless is_swagger_2_0? || is_openapi_3_0?
 
           self.data[:tags] ||= []
           self.data[:tags] << Swagger::Blocks::Nodes::TagNode.call(version: version, inline_keys: inline_keys, &block)
         end
 
+        def server(inline_keys = nil, &block)
+          raise NotSupportedError unless is_openapi_3_0?
+
+          self.data[:servers] ||= []
+          self.data[:servers] << Swagger::Blocks::Nodes::ServerNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def extension(name, inline_keys = nil, &block)
+          raise NotSupportedError unless is_openapi_3_0?
+
+          self.data[name] ||= []
+          self.data[name] << Swagger::Blocks::Nodes::VendorExtensionNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
         # Use 'tag' instead.
         # @deprecated
         alias_method :tags, :tag

data/lib/swagger/blocks/nodes/schema_node.rb

@@ -24,6 +24,15 @@ module Swagger
         def externalDocs(inline_keys = nil, &block)
           self.data[:externalDocs] = Swagger::Blocks::Nodes::ExternalDocsNode.call(version: version, inline_keys: inline_keys, &block)
         end
+
+        def example(inline_keys = nil, &block)
+          self.data[:example] = Swagger::Blocks::Nodes::ExampleNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+
+        def one_of(&block)
+          self.data[:oneOf] ||= []
+          self.data[:oneOf] << Swagger::Blocks::Nodes::OneOfNode.call(version: version, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/scopes_node.rb

@@ -1,7 +1,6 @@
 module Swagger
   module Blocks
     module Nodes
-      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#scopes-object
       class ScopesNode < Node
       end
     end

data/lib/swagger/blocks/nodes/security_scheme_node.rb

@@ -1,13 +1,17 @@
 module Swagger
   module Blocks
     module Nodes
-      # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-scheme-object
       class SecuritySchemeNode < Node
         # TODO support ^x- Vendor Extensions
 
         def scopes(inline_keys = nil, &block)
           self.data[:scopes] = Swagger::Blocks::Nodes::ScopesNode.call(version: version, inline_keys: inline_keys, &block)
         end
+
+        def flow(name, inline_keys = nil, &block)
+          self.data[:flows] ||= {}
+          self.data[:flows][name] = Swagger::Blocks::Nodes::FlowNode.call(version: version, inline_keys: inline_keys, &block)
+        end
       end
     end
   end

data/lib/swagger/blocks/nodes/server_node.rb

@@ -0,0 +1,12 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class ServerNode < Node
+        def variable(name, inline_keys = nil, &block)
+          self.data[:variables] ||= {}
+          self.data[:variables][name] = Swagger::Blocks::Nodes::VariableNode.call(version: version, inline_keys: inline_keys, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/value_node.rb

@@ -0,0 +1,8 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class ValueNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/variable_node.rb

@@ -0,0 +1,8 @@
+module Swagger
+  module Blocks
+    module Nodes
+      class VariableNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/nodes/vendor_extension_node.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Blocks
+    module Nodes
+      # v3.0: https://swagger.io/docs/specification/openapi-extensions/
+      class VendorExtensionNode < Node
+      end
+    end
+  end
+end

data/lib/swagger/blocks/root.rb

@@ -19,7 +19,14 @@ module Swagger
         end
       end
 
-      data[:root_node].as_json
+      if data[:root_node].is_openapi_3_0?
+        data[:root_node].key(:paths, data[:path_nodes]) # Required, so no empty check.
+        if data[:component_node] && !data[:component_node].data.empty?
+          data[:root_node].key(:components, data[:component_node])
+        end
+      end
+
+      data[:root_node].as_json(version: data[:root_node].version)
     end
   end
 end

data/lib/swagger/blocks/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Blocks
-    VERSION = '2.0.2'
+    VERSION = '3.0.0'
   end
 end

data/spec/lib/swagger_v2_blocks_spec.rb

@@ -328,7 +328,7 @@ describe 'Swagger::Blocks v2' do
         Swagger::Blocks.build_root_json([])
       }.to raise_error(Swagger::Blocks::DeclarationError)
     end
-    it 'errors if mulitple swagger_roots are declared' do
+    it 'errors if multiple swagger_roots are declared' do
       expect {
         Swagger::Blocks.build_root_json([PetControllerV2, PetControllerV2])
       }.to raise_error(Swagger::Blocks::DeclarationError)

data/spec/lib/swagger_v3_api_declaration.json

@@ -0,0 +1,592 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.1",
+    "title": "Swagger Petstore",
+    "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
+    "termsOfService": "http://helloreverb.com/terms/",
+    "contact": {
+      "name": "Wordnik API Team"
+    },
+    "license": {
+      "name": "MIT"
+    }
+  },
+  "servers": [
+    {
+      "url": "http://petstore.swagger.io/v1",
+      "description": "Petstore API"
+    },
+    {
+      "url": "https://{subdomain}.site.com/{version}",
+      "description": "The main prod server",
+      "variables": {
+        "subdomain": {
+          "default": "production"
+        },
+        "version": {
+          "enum": [
+            "v1",
+            "v2"
+          ],
+          "default": "v2"
+        }
+      }
+    }
+  ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    },
+    {
+      "OAuth2": [
+        "read",
+        "write"
+      ]
+    }
+  ],
+  "x-tagGroups": [
+    {
+      "name": "Pets",
+      "tags": ["dogs", "cats"]
+    }
+  ],
+  "tags": [
+    {
+      "name": "dogs",
+      "description": "Dogs"
+    },
+    {
+      "name": "cats",
+      "description": "Cats"
+    }
+  ],
+  "paths": {
+    "/pets": {
+      "description": "Perform actions on pet resources",
+      "servers": [
+        {
+          "url": "http://petstore.swagger.io/",
+          "description": "Petstore API (without version prefix)"
+        }
+      ],
+      "get": {
+        "summary": "List all pets",
+        "operationId": "listPets",
+        "tags": [
+          "pets"
+        ],
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "How many items to return at one time (max 100)",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32"
+            },
+            "examples": {
+              "large": {
+                "value": 100,
+                "summary": "Return a maximum of 100 results"
+              },
+              "small": {
+                "value": 5,
+                "summary": "Return a maximum of 5 results"
+              }
+            }
+          }
+        ],
+        "servers": [
+          {
+            "url": "http://petstore.swagger.io/2.1/",
+            "description": "Petstore API (with version 2.1 prefix)"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A paged array of pets",
+            "headers": {
+              "x-next": {
+                "description": "A link to the next page of responses",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pets"
+                },
+                "examples": {
+                  "Rabbit": {
+                    "value": {
+                      "id": 10,
+                      "name": "Rabbit"
+                    }
+                  },
+                  "Cat": {
+                    "$ref": "#/components/examples/Cat"
+                  }
+                }
+              }
+            },
+            "links": {
+              "getPetById": {
+                "$ref": "#/components/links/GetPetById"
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a pet",
+        "operationId": "createPets",
+        "tags": [
+          "pets"
+        ],
+        "requestBody": {
+          "description": "Pet to add to the store",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "example": {
+                  "name": "Fluffy"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "New Pet",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pet"
+                }
+              }
+            },
+            "links": {
+              "getPetById": {
+                "operationId": "showPetById",
+                "parameters": {
+                  "id": "$response.body#/id"
+                },
+                "description": "The `id` value returned in the response can be used as the `petId` parameter in `GET /pets/{petId}`."
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pets/{petId}": {
+      "parameters": [
+        {
+          "name": "petId",
+          "in": "path",
+          "required": true,
+          "description": "The id of the pet to retrieve",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "get": {
+        "summary": "Info for a specific pet",
+        "operationId": "showPetById",
+        "tags": [
+          "pets"
+        ],
+        "responses": {
+          "200": {
+            "description": "Expected response to a valid request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pet"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Update info for a specific pet",
+        "operationId": "updatePetById",
+        "tags": [
+          "pets"
+        ],
+        "requestBody": {
+          "$ref": "#/components/requestBodies/PetBody"
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/UpdatePetBodyResponse"
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "summary": "Replace info for a specific pet",
+        "operationId": "replacePetById",
+        "tags": [
+          "pets"
+        ],
+        "requestBody": {
+          "$ref": "#/components/requestBodies/PetBody"
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/ReplacePetBodyResponse"
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pets/{petId}/purchase": {
+      "post": {
+        "summary": "Purchase a specific pet",
+        "operationId": "purchasePetById",
+        "deprecated": true,
+        "tags": [
+          "pets"
+        ],
+        "parameters": [
+          {"$ref": "#/components/parameters/petId"}
+        ],
+        "requestBody": {
+          "description": "Pet order object",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "oneOf": [
+                  {"$ref": "#/components/schemas/PetOrderRequest"},
+                  {"$ref": "#/components/schemas/ComplexPetOrderRequest"}
+                ]
+              },
+              "example": {
+                "id": 10,
+                "name": "Fluffy"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Expected response to a valid request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PetOrder"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "callbacks": {
+          "orderUpdated": {
+            "{$request.body#/webhook_url}": {
+              "post": {
+                "requestBody": {
+                  "required": true,
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "$ref": "#/components/schemas/OrderUpdated"
+                      }
+                    }
+                  }
+                },
+                "responses": {
+                  "200": {
+                    "description": "The server must return an HTTP 200, otherwise delivery will be reattempted."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pet": {
+        "required": [
+          "id",
+          "name"
+        ],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "name": {
+            "type": "string"
+          },
+          "tag_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "example": 1
+            },
+            "example": [1, 2, 3]
+          }
+        }
+      },
+      "Pets": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/Pet"
+        },
+        "example": [{"id": 10, "name": "Rover"}, {"id": 20, "name": "Felicity"}]
+      },
+      "PetOrderRequest": {
+        "required": [
+          "phone_number"
+        ],
+        "properties": {
+          "phone_number": {
+            "type": "string"
+          },
+          "webhook_url": {
+            "type": "string"
+          }
+        }
+      },
+      "PetOrder": {
+        "required": [
+          "phone_number",
+          "id",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "phone_number": {
+            "type": "string"
+          },
+          "webhook_url": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        }
+      },
+      "OrderUpdated": {
+        "required": [
+          "order_id",
+          "status",
+          "phone_number"
+        ],
+        "properties": {
+          "order_id": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "phone_number": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        },
+        "example": {
+          "order_id": 123,
+          "phone_number": "3125556666",
+          "status": "complete"
+        }
+      },
+      "Error": {
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "requestBodies": {
+      "PetBody": {
+        "description": "A JSON object containing pet information",
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Pet"
+            }
+          }
+        }
+      }
+    },
+    "responses" : {
+      "UpdatePetBodyResponse": {
+        "description": "Expected response to a valid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Pet"
+            }
+          }
+        }
+      },
+      "ReplacePetBodyResponse": {
+        "description": "Expected response to a valid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Pet"
+            }
+          }
+        }
+      }
+    },
+    "links": {
+      "GetPetById": {
+        "operationId": "showPetById",
+        "parameters": {
+          "petId": "$response.body#/id"
+        }
+      }
+    },
+    "examples": {
+      "PetExample": {
+        "value": {
+          "id": 1,
+          "name": "Rover"
+        },
+        "summary": "An example pet response"
+      },
+      "Cat": {
+        "value": {
+          "id": 1,
+          "name": "Felicity"
+        },
+        "summary": "An example cat response"
+      }
+    },
+    "securitySchemes": {
+      "BasicAuth": {
+        "type": "http",
+        "scheme": "basic"
+      },
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      },
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key"
+      },
+      "OpenID": {
+        "type": "openIdConnect",
+        "openIdConnectUrl": "https://example.com/.well-known/openid-configuration"
+      },
+      "OAuth2": {
+        "type": "oauth2",
+        "flows": {
+          "authorizationCode": {
+            "authorizationUrl": "https://example.com/oauth/authorize",
+            "tokenUrl": "https://example.com/oauth/token",
+            "scopes": {
+              "read": "Grants read access",
+              "write": "Grants write access",
+              "admin": "Grants access to admin operations"
+            }
+          }
+        }
+      }
+    },
+    "parameters": {
+      "petId": {
+        "name": "petId",
+        "in": "path",
+        "required": true,
+        "description": "The id of the pet to retrieve",
+        "schema": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}