openapi3_parser 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 651f457272264ca4fc7b45040203a9fa7deeabde
-  data.tar.gz: b00561ee20a2c121d9f1d030511b07870cd66ecc
+  metadata.gz: 39b97559bdb240544c9f0f65b848c71edc28af1c
+  data.tar.gz: b8b1339e8d116a202a16ada58ffb75cf403f608f
 SHA512:
-  metadata.gz: a38facc684d56b0194066ba88db7396107d882bc225fa07f14600bf21a5156c2f6032f8b284bac5146a6f3a9e792147e63fd35ca915b8b8d2f36fe57e738a662
-  data.tar.gz: f605fd5997afe6055b6e627eaca9971dd60dd6f2fbc19381a363490a596f46cf001317aed21130c4273115143c6353516c035747ab16867b62ece619434b6b1a
+  metadata.gz: 5a9772d8bfd2c67b3736f32aa25d937c08c1fc76f8142bc92685f3cc2f0202a7c74f313d6e836d1ddcf92b15b99084b94e056d53ed299b437eefd15f56387eff
+  data.tar.gz: c47362a370307d40b1497e8b1c67e58ce267efaa611e0f0b49765ab3f2769635aba04f67f611250a1125116cadca09ac4d6d6372290253069192336c641169ba

data/.rubocop.yml

@@ -7,3 +7,7 @@ Documentation:
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*.rb'
+Naming/UncommunicativeMethodParamName:
+  Enabled: false
+Naming/UncommunicativeBlockParamName:
+  Enabled: false

data/.travis.yml

@@ -1,13 +1,11 @@
 language: ruby
 sudo: false
 rvm:
-  - 2.3.6
-  - 2.4.3
-  - jruby-9.1.15.0
+  - 2.3.7
+  - 2.4.4
+  - 2.5.1
   - ruby-head
-  - jruby-head
 matrix:
   allow_failures:
     - rvm: ruby-head
-    - rvm: jruby-head
   fast_finish: true

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.4.0
+
+- Determine the OpenAPI specification version and store it in document.
+- Support commonmark rendering, add description_html methods to nodes which
+  allow description to be rendered as HTML.
+- Fix bug with CGI constant unresolved
+
 # 0.3.0
 
 - Allow opening files by URL

data/README.md

@@ -23,7 +23,7 @@ Documentation for the API to navigate the OpenAPI nodes is available on
 [rubydoc.info][docs].
 
 [openapi-3]: https://github.com/OAI/OpenAPI-Specification
-[docs]: http://www.rubydoc.info/github/kevindew/openapi3_parser/Openapi3Parser/Nodes/Openapi
+[docs]: http://www.rubydoc.info/github/kevindew/openapi3_parser/Openapi3Parser/Node/Openapi
 
 ## Installation
 
@@ -31,7 +31,7 @@ You can install this gem into your bundler application by adding this line to
 your Gemfile:
 
 ```
-gem "openapi3_parser", "~> 0.2.0"
+gem "openapi3_parser", "~> 0.3.0"
 ```
 
 and then running `$ bundle install`

data/TODO.md

@@ -2,7 +2,7 @@
 
 These are the steps defined to reach 1.0. Assistance is very welcome.
 
-- [ ] Handle mutually exclusive fields
+- [x] Handle mutually exclusive fields
 - [ ] Refactor the various NodeFactory modules to be a less confusing
       hierachical structure. Consider having factories subclass instead of use
       mixin
@@ -14,7 +14,7 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [x] Allow opening of openapi documents by URL
 - [x] Support references by URL
 - [ ] Consider option to limit open by URL/path behaviour
-- [ ] Support converting CommonMark to HTML
+- [x] Support converting CommonMark to HTML
 - [ ] Reach parity with OpenAPI specification for validation
 - [ ] Consider a lenient mode for a document to only have to comply with type
       based validation
@@ -32,3 +32,10 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [x] Ensure Array and Map nodes return empty ones by default rather than nil
 - [ ] Make JSON pointer public access to be consistent accepting string, array
       or (potentially) a pointer class
+- [ ] Support creating a default Server object on servers property of OpenAPI
+      Node
+- [ ] Support relative URLs being able to be relative the first server object
+      see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#relative-references-in-urls
+- [ ] Support validating a Server URL based on default values
+- [ ] Validate paths to check path parameters within them appear in paths
+      see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#fixed-fields-10

data/lib/openapi3_parser/context/pointer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module Openapi3Parser
   class Context
     # A class to decorate the array of fields that make up a pointer and

data/lib/openapi3_parser/document.rb

@@ -13,12 +13,21 @@ module Openapi3Parser
   # Document is the root construct of a created OpenAPI Document and can be
   # used to navigate the contents of a document or to check it's validity.
   #
-  # @attr_reader  [Source] root_source
+  # @attr_reader  [String]        openapi_version
+  # @attr_reader  [Source]        root_source
+  # @attr_reader  [Array<String>] warnings
   class Document
     extend Forwardable
     include Enumerable
 
-    attr_reader :root_source
+    attr_reader :openapi_version, :root_source, :warnings
+
+    # A collection of the openapi versions that are supported
+    SUPPORTED_OPENAPI_VERSIONS = %w[3.0].freeze
+
+    # The version of OpenAPI that will be used by default for
+    # validation/construction
+    DEFAULT_OPENAPI_VERSION = "3.0"
 
     # @!method valid?
     #   Whether this OpenAPI document has any validation issues or not. See
@@ -29,36 +38,36 @@ module Openapi3Parser
 
     # @!method openapi
     #   The value of the openapi version field for this document
-    #   @see Nodes::Openapi#openapi
+    #   @see Node::Openapi#openapi
     #   @return [String]
     # @!method info
     #   The value of the info field on the OpenAPI document
-    #   @see Nodes::Openapi#info
-    #   @return [Nodes::Info]
+    #   @see Node::Openapi#info
+    #   @return [Node::Info]
     # @!method servers
     #   The value of the servers field on the OpenAPI document
-    #   @see Nodes::Openapi#servers
-    #   @return [Nodes::Array<Nodes::Server>]
+    #   @see Node::Openapi#servers
+    #   @return [Node::Array<Node::Server>]
     # @!method paths
     #   The value of the paths field on the OpenAPI document
-    #   @see Nodes::Openapi#paths
-    #   @return [Nodes::Paths]
+    #   @see Node::Openapi#paths
+    #   @return [Node::Paths]
     # @!method components
     #   The value of the components field on the OpenAPI document
-    #   @see Nodes::Openapi#components
-    #   @return [Nodes::Components]
+    #   @see Node::Openapi#components
+    #   @return [Node::Components]
     # @!method security
     #   The value of the security field on the OpenAPI document
-    #   @see Nodes::Openapi#security
-    #   @return [Nodes::Array<Nodes::SecurityRequirement>]
+    #   @see Node::Openapi#security
+    #   @return [Node::Array<Node::SecurityRequirement>]
     # @!method tags
     #   The value of the tags field on the OpenAPI document
-    #   @see Nodes::Openapi#tags
-    #   @return [Nodes::Array<Nodes::Tag>]
+    #   @see Node::Openapi#tags
+    #   @return [Node::Array<Node::Tag>]
     # @!method external_docs
     #   The value of the external_docs field on the OpenAPI document
-    #   @see Nodes::Openapi#external_docs
-    #   @return [Nodes::ExternalDocumentation]
+    #   @see Node::Openapi#external_docs
+    #   @return [Node::ExternalDocumentation]
     # @!method extension
     #   Look up an extension field provided for the root object of the document
     #   @see Node::Object#extension
@@ -78,11 +87,13 @@ module Openapi3Parser
     def initialize(source_input)
       @reference_register = ReferenceRegister.new
       @root_source = Source.new(source_input, self, reference_register)
+      @warnings = []
+      @openapi_version = determine_openapi_version(root_source.data["openapi"])
       @build_in_progress = false
       @built = false
     end
 
-    # @return [Nodes::Openapi]
+    # @return [Node::Openapi]
     def root
       factory.node
     end
@@ -125,16 +136,41 @@ module Openapi3Parser
 
     attr_reader :reference_register, :built, :build_in_progress
 
+    def add_warning(text)
+      @warnings << text
+    end
+
     def build
       return if build_in_progress || built
       @build_in_progress = true
       context = Context.root(root_source.data, root_source)
       @factory = NodeFactories::Openapi.new(context)
       reference_register.freeze
+      @warnings.freeze
       @build_in_progress = false
       @built = true
     end
 
+    def determine_openapi_version(version)
+      minor_version = (version || "").split(".").first(2).join(".")
+
+      if SUPPORTED_OPENAPI_VERSIONS.include?(minor_version)
+        minor_version
+      elsif version
+        add_warning(
+          "Unsupported OpenAPI version (#{version}), treating as a " \
+          "#{DEFAULT_OPENAPI_VERSION} document"
+        )
+        DEFAULT_OPENAPI_VERSION
+      else
+        add_warning(
+          "Unspecified OpenAPI version, treating as a " \
+          "#{DEFAULT_OPENAPI_VERSION} document"
+        )
+        DEFAULT_OPENAPI_VERSION
+      end
+    end
+
     def factory
       build unless built
       @factory

data/lib/openapi3_parser/markdown.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "commonmarker"
+
+module Openapi3Parser
+  # Wrapper around a gem to render markdown, used a single place for options
+  # and handling the gem
+  module Markdown
+    # @param  [String]  text
+    # @return [String]
+    def self.to_html(text)
+      CommonMarker.render_doc(text).to_html
+    end
+  end
+end

data/lib/openapi3_parser/{nodes → node}/array.rb

@@ -3,7 +3,7 @@
 require "openapi3_parser/node/map"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # An array within a OpenAPI document.
     # Very similar to a normal Ruby array, however this is read only and knows
     # the context of where it sits in an OpenAPI document

data/lib/openapi3_parser/{nodes → node}/callback.rb

@@ -3,10 +3,8 @@
 require "openapi3_parser/node/map"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callbackObject
-    class Callback
-      include Node::Map
-    end
+    class Callback < Node::Map; end
   end
 end

data/lib/openapi3_parser/{nodes → node}/components.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject
-    class Components
-      include Node::Object
-
+    class Components < Node::Object
       # @return [Map<String, Schema>]
       def schemas
         node_data["schemas"]

data/lib/openapi3_parser/{nodes → node}/contact.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#contactObject
-    class Contact
-      include Node::Object
-
+    class Contact < Node::Object
       # @return [String, nil]
       def name
         data["name"]

data/lib/openapi3_parser/{nodes → node}/discriminator.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject
-    class Discriminator
-      include Node::Object
-
+    class Discriminator < Node::Object
       # @return [String]
       def property_name
         node_data["propertyName"]

data/lib/openapi3_parser/{nodes → node}/encoding.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#encodingObject
-    class Encoding
-      include Node::Object
-
+    class Encoding < Node::Object
       # @return [String, nil]
       def content_type
         node_data["contentType"]

data/lib/openapi3_parser/{nodes → node}/example.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#exampleObject
-    class Example
-      include Node::Object
-
+    class Example < Node::Object
       # @return [String, nil]
       def summary
         node_data["summary"]
@@ -18,6 +16,11 @@ module Openapi3Parser
         node_data["description"]
       end
 
+      # @return [String, nil]
+      def description_html
+        render_markdown(description)
+      end
+
       # @return [Object]
       def value
         node_data["value"]

data/lib/openapi3_parser/{nodes → node}/external_documentation.rb

@@ -3,16 +3,19 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#externalDocumentationObject
-    class ExternalDocumentation
-      include Node::Object
-
+    class ExternalDocumentation < Node::Object
       # @return [String, nil]
       def description
         node_data["description"]
       end
 
+      # @return [String, nil]
+      def description_html
+        render_markdown(description)
+      end
+
       # @return [String]
       def url
         node_data["url"]

data/lib/openapi3_parser/{nodes → node}/header.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require "openapi3_parser/node/object"
-require "openapi3_parser/nodes/parameter/parameter_like"
+require "openapi3_parser/node/parameter_like"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#headerObject
-    class Header
-      include Node::Object
-      include Parameter::ParameterLike
+    class Header < Node::Object
+      include ParameterLike
     end
   end
 end

data/lib/openapi3_parser/{nodes → node}/info.rb

@@ -3,22 +3,25 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#infoObject
-    class Info
-      include Node::Object
-
+    class Info < Node::Object
       # @return [String]
       def title
         node_data["title"]
       end
 
-      # @return [String, null]
+      # @return [String, nil]
       def description
         node_data["description"]
       end
 
-      # @return [String, null]
+      # @return [String, nil]
+      def description_html
+        render_markdown(description)
+      end
+
+      # @return [String, nil]
       def terms_of_service
         node_data["termsOfService"]
       end

data/lib/openapi3_parser/{nodes → node}/license.rb

@@ -3,11 +3,9 @@
 require "openapi3_parser/node/object"
 
 module Openapi3Parser
-  module Nodes
+  module Node
     # @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#licenseObject
-    class License
-      include Node::Object
-
+    class License < Node::Object
       # @return [String]
       def name
         node_data["name"]