zero-rails_openapi 1.0.0

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/examples/examples_controller.rb

@@ -0,0 +1,36 @@
+class Api::V1::ExamplesController < Api::V1::BaseController
+  apis_set 'ExamplesController\'s APIs' do
+    schema :Dog           => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+    path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
+    query! :QueryCompUuid => [ :product_uuid, { uuid: String, time: 'int32' }, desc: 'product uuid' ]
+    body!  :RqBodyComp    => [ :form ]
+    resp   :RespComp      => [ 'bad request', :json ]
+  end
+
+  open_api_set %i[index show], 'common response' do
+    response '567', 'query result export', :pdf, type: File
+  end
+
+  open_api :index, '(SUMMARY) this api blah blah ...' do
+    this_api_is_invalid! 'this api is expired!'
+    desc 'Optional multiline or single-line Markdown-formatted description',
+         id:         'user id',
+         email_addr: 'email_addr\'s desc'
+    email = 'git@github.com'
+
+    query! :id,         Integer, enum: 0..5,     length: [1, 2], pattern: /^[0-9]$/, range: {gt:0, le:5}
+    query! :done,       Boolean, must_be: false, default: true,  desc: 'must be false'
+    query  :email_addr, String,  lth: :ge_3,     default: email  # is_a: :email
+    # form! 'form', type: { id!: Integer, name: String }
+    file :pdf, 'desc: the media type is application/pdf'
+
+    response :success, 'success response', :json, type: :Dog
+
+    security :ApiKeyAuth
+  end
+
+  open_api :show do
+    param_ref    :PathCompId, :QueryCompUuid
+    response_ref '123' => :RespComp, '223' => :RespComp
+  end
+end

data/lib/examples/open_api.rb

@@ -0,0 +1,87 @@
+require 'open_api'
+
+OpenApi.configure do |c|
+  # [REQUIRED] The location where .json doc file will be output.
+  c.file_output_path = 'public/open_api'
+
+  # Everything about OAS3 is on https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md
+  # Getting started: https://swagger.io/docs/specification/basic-structure/
+  c.register_apis = {
+      homepage_api: {
+          # [REQUIRED] ZRO will scan all the descendants of the root_controller, then generate their docs.
+          root_controller: Api::V1::BaseController,
+
+          # [REQUIRED] Info Object: The info section contains API information
+          info: {
+              # [REQUIRED] The title of the application.
+              title: 'Zero Rails APIs',
+              # Description of the application.
+              description: 'API documentation of Zero-Rails Application. <br/>' \
+                           'Optional multiline or single-line Markdown-formatted description ' \
+                           'in [CommonMark](http://spec.commonmark.org/) or `HTML`.',
+              # A URL to the Terms of Service for the API. MUST be in the format of a URL.
+              # termsOfService: 'http://example.com/terms/',
+              # Contact Object: The contact information for the exposed API.
+              contact: {
+                  # The identifying name of the contact person/organization.
+                  name: 'API Support',
+                  # The URL pointing to the contact information. MUST be in the format of a URL.
+                  url: 'http://www.github.com',
+                  # The email address of the contact person/organization. MUST be in the format of an email address.
+                  email: 'git@gtihub.com'
+              },
+              # License Object: The license information for the exposed API.
+              license: {
+                  # [REQUIRED] The license name used for the API.
+                  name: 'Apache 2.0',
+                  # A URL to the license used for the API. MUST be in the format of a URL.
+                  url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+              },
+              # [REQUIRED] The version of the OpenAPI document
+              # (which is distinct from the OpenAPI Specification version or the API implementation version).
+              version: '1.0.0'
+          },
+
+          # An array of Server Objects, which provide connectivity information to a target server.
+          # If the servers property is not provided, or is an empty array,
+          #   the default value would be a Server Object with a url value of /.
+          # https://swagger.io/docs/specification/api-host-and-base-path/
+          #   The servers section specifies the API server and base URL.
+          #   You can define one or several servers, such as production and sandbox.
+          servers: [{
+                        # [REQUIRED] A URL to the target host.
+                        # This URL supports Server Variables and MAY be relative,
+                        #   to indicate that the host location is relative to the location where
+                        #   the OpenAPI document is being served.
+                        url: 'http://localhost:2333/api/v1',
+                        # An optional string describing the host designated by the URL.
+                        description: 'Optional server description, e.g. Main (production) server'
+                    },{
+                        url: 'http://localhost:3332/api/v1',
+                        description: 'Optional server description, e.g. Internal staging server for testing'
+                    }],
+
+          # Authentication
+          #   The securitySchemes and security keywords are used to describe the authentication methods used in your API.
+          # Security Scheme Object: An object to hold reusable Security Scheme Objects.
+          global_security_schemes: {
+              ApiKeyAuth: {
+                  type: 'apiKey',
+                  name: 'server_token',
+                  in: 'query'
+              }
+          },
+          # Security Requirement Object
+          #   A declaration of which security mechanisms can be used across the API.
+          #   The list of values includes alternative security requirement objects that can be used.
+          #   Only one of the security requirement objects need to be satisfied to authorize a request.
+          #   Individual operations can override this definition.
+          # see: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#securityRequirementObject
+          global_security: [{ ApiKeyAuth: [] }],
+      }
+  }
+end
+
+Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL
+
+OpenApi.write_docs # Generate doc when Rails initializing

data/lib/oas_objs/helpers.rb

@@ -0,0 +1,41 @@
+module OpenApi
+  module Helpers
+
+    # TODO: comment-block doc
+    def truly_present?(obj)
+      obj == false || obj.present?
+    end
+
+    def value_present
+      Proc.new { |_, v| truly_present? v }
+    end
+
+    def assign(value)
+      @assign = value.is_a?(Symbol)? self.send("_#{value}") : value
+      self
+    end
+
+    def all(*values)
+      @assign = values.compact.reduce({ }, :merge).keep_if &value_present
+      self
+    end
+
+    def to_processed(who)
+      if who.is_a?(Symbol)
+        self.send("#{who}=", @assign)
+      else
+        processed[who.to_sym] = @assign
+      end if truly_present?(@assign)
+
+      processed
+    end
+
+    def to(who)
+      self[who.to_sym] = @assign if truly_present?(@assign)
+    end
+
+    def for_merge # to_processed
+      processed.tap { |it| it.merge! @assign if truly_present?(@assign) }
+    end
+  end
+end

data/lib/oas_objs/media_type_obj.rb

@@ -0,0 +1,86 @@
+require 'oas_objs/schema_obj'
+
+module OpenApi
+  module DSL
+    # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#media-type-object
+    class MediaTypeObj < Hash
+      attr_accessor :media_type, :schema
+      def initialize(media_type, schema_hash)
+        self.media_type = media_type_mapping media_type
+        self.schema     = SchemaObj.new(schema_hash[:type], schema_hash)
+      end
+
+      def process
+        schema_processed = self.schema.process
+        schema = schema_processed.values.join.blank? ? { } : { schema: schema_processed }
+        media_type.nil? ? { } : { media_type =>  schema }
+      end
+
+      # https://swagger.io/docs/specification/media-types/
+      # https://en.wikipedia.org/wiki/Media_type
+      # https://zh.wikipedia.org/wiki/%E4%BA%92%E8%81%94%E7%BD%91%E5%AA%92%E4%BD%93%E7%B1%BB%E5%9E%8B
+      # https://www.iana.org/assignments/media-types/media-types.xhtml
+      def media_type_mapping(media_type)
+        return media_type if media_type.is_a? String
+        case media_type
+          when :app;   'application/*'
+          when :json;  'application/json'
+          when :xml;   'application/xml'
+          when :xwww;  'application/x-www-form-urlencoded'
+          when :pdf;   'application/pdf'
+          when :zip;   'application/zip'
+          when :gzip;  'application/gzip'
+          when :doc;   'application/msword'
+          when :docx;  'application/application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+          when :xls;   'application/vnd.ms-excel'
+          when :xlsx;  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+          when :ppt;   'application/vnd.ms-powerpoint'
+          when :pptx;  'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+          # when :pdf;   'application/pdf'
+          when :form;  'multipart/form-data'; when :form_data; 'multipart/form-data'
+          when :text;  'text/*'
+          when :plain; 'text/plain; charset=utf-8'
+          when :html;  'text/html'
+          when :csv;   'text/csv'
+          when :image; 'image/*'
+          when :png;   'image/png'
+          when :jpeg;  'image/jpeg'
+          when :gif;   'image/gif'
+          when :audio; 'audio/*'
+          when :video; 'video/*'
+          else;        nil
+        end
+      end
+    end
+  end
+end
+
+
+__END__
+
+Media Type Examples
+
+{
+  "application/json": {
+    "schema": {
+         "$ref": "#/components/schemas/Pet"
+    },
+    "examples": {
+      "cat" : {
+        "summary": "An example of a cat",
+        "value":
+          {
+            "name": "Fluffy",
+            "petType": "Cat",
+            "color": "White",
+            "gender": "male",
+            "breed": "Persian"
+          }
+      },
+      "frog": {
+          "$ref": "#/components/examples/frog-example"
+        }
+      }
+    }
+  }
+}

data/lib/oas_objs/param_obj.rb

@@ -0,0 +1,83 @@
+require 'oas_objs/helpers'
+require 'oas_objs/schema_obj'
+
+module OpenApi
+  module DSL
+    class ParamObj < Hash
+      include Helpers
+
+      attr_accessor :processed, :schema
+      def initialize(name, param_type, type, required, schema_hash)
+        self.processed = {
+            name: name,
+            in: param_type,
+            required: "#{required}".match?(/req/),
+        }
+        self.schema = SchemaObj.new(type, schema_hash)
+        self.merge! schema_hash
+      end
+
+      def process
+        assign(_desc).to_processed 'description'
+        processed.tap { |it| it[:schema] = schema.process_for name }
+      end
+
+
+      # Getters and Setters of the original values that was passed to param()
+      # This mapping allows user to select the aliases in DSL writing,
+      #   without increasing the complexity of the implementation.
+      { # SELF_MAPPING
+          _range:  %i[range   number_range],
+          _length: %i[length  lth         ],
+          _desc:   %i[desc    description ],
+      }.each do |key, aliases|
+        define_method key do
+          aliases.each { |alias_name| self[key] ||= self[alias_name] } if self[key].nil?
+          self[key]
+        end
+      end
+
+
+      # Interfaces for directly taking the info what you focus on,
+      #   The next step you may want to verify the parameters based on these infos.
+      #   The implementation of the parameters validator, see:
+      #     TODO
+      alias_method :range, :_range
+      alias_method :length, :_length
+      { # INTERFACE_MAPPING
+          name:     %i[name          ],
+          required: %i[required      ],
+          in:       %i[in            ],
+          enum:     %i[schema enum   ],
+          pattern:  %i[schema pattern],
+          regexp:   %i[schema pattern],
+          type:     %i[schema type   ],
+          is:       %i[schema format ],
+      }.each do |method, path|
+        define_method method do path.inject(processed, &:[]) end # Get value from hash by key path
+      end
+      alias_method :required?, :required
+    end
+  end
+end
+
+
+__END__
+
+Parameter Object Examples
+A header parameter with an array of 64 bit integer numbers:
+
+{
+  "name": "token",
+  "in": "header",
+  "description": "token to be passed as a header",
+  "required": true,
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "integer",
+      "format": "int64"
+    }
+  },
+  "style": "simple"
+}

data/lib/oas_objs/ref_obj.rb

@@ -0,0 +1,29 @@
+require 'oas_objs/media_type_obj'
+require 'oas_objs/helpers'
+
+module OpenApi
+  module DSL
+    # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#referenceObject
+    class RefObj < Hash
+      include Helpers
+
+      attr_accessor :processed
+      def initialize(ref_to, component_key)
+        self.processed = {
+            '$ref': "#components/#{ref_to}s/#{component_key}"
+        }
+      end
+
+      def process; processed; end
+    end
+  end
+end
+
+
+__END__
+
+Reference Object Example
+
+{
+	"$ref": "#/components/schemas/Pet"
+}

data/lib/oas_objs/request_body_obj.rb

@@ -0,0 +1,54 @@
+require 'oas_objs/media_type_obj'
+require 'oas_objs/helpers'
+
+module OpenApi
+  module DSL
+    # https://swagger.io/docs/specification/describing-request-body/
+    # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject
+    class RequestBodyObj < Hash
+      include Helpers
+
+      attr_accessor :processed, :media_type
+      def initialize(required, media_type, desc, schema_hash)
+        self.media_type = MediaTypeObj.new(media_type, schema_hash)
+        self.processed  = { required: "#{required}".match?(/req/), description: desc }
+      end
+
+      def process
+        assign(media_type.process).to_processed 'content'
+        processed
+      end
+    end
+  end
+end
+
+
+__END__
+
+Request Body Examples
+A request body with a referenced model definition.
+
+{
+  "description": "user to add to the system",
+  "content": {
+    "application/json": {
+      "schema": {
+        "$ref": "#/components/schemas/User"
+      },
+      "examples": {
+          "user" : {
+            "summary": "User Example",
+            "externalValue": "http://foo.bar/examples/user-example.json"
+          }
+        }
+    },
+    "*/*": {
+      "examples": {
+        "user" : {
+            "summary": "User example in other format",
+            "externalValue": "http://foo.bar/examples/user-example.whatever"
+        }
+      }
+    }
+  }
+}

data/lib/oas_objs/response_obj.rb

@@ -0,0 +1,44 @@
+require 'oas_objs/media_type_obj'
+require 'oas_objs/helpers'
+
+module OpenApi
+  module DSL
+    # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#responseObject
+    class ResponseObj < Hash
+      include Helpers
+
+      attr_accessor :processed, :code, :media_type
+      def initialize(code, desc, media_type, schema_hash)
+        self.code       = "#{code}"
+        self.media_type = MediaTypeObj.new(media_type, schema_hash)
+        self.processed  = { description: desc }
+      end
+
+      def process
+        assign(media_type.process).to_processed 'content'
+        { code => processed }
+      end
+    end
+  end
+end
+
+
+__END__
+
+Response Object Examples
+
+Response of an array of a complex type:
+
+{
+  "description": "A complex object array response",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/VeryComplexType"
+        }
+      }
+    }
+  }
+}