zero-rails_openapi 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c0a2065e4a332132fafda9c0b20dc1f10a87ba0
-  data.tar.gz: 8e232f1841f6489ec5fba6e9c3aaf56e0314e416
+  metadata.gz: ade759189024d01051f73655ca7f55d14264598c
+  data.tar.gz: f97aa2a93a2b88af05e8326e5d1ef894a205cc47
 SHA512:
-  metadata.gz: 24baf84b60c4e2b4a846d5284b34fef596444d1ee90f35fa537d2de87af6b7e35999b44e780db9fbd1a8450675bfe558d9b2d77a51774f120d8133d2fef08f8a
-  data.tar.gz: c238aa68acdc0be8a9d7c3482828ab7feedc69088161622bace745b801111bc28184a9a0612ccb774b5c6accf630e3258c86c88cf160a0e2ee9534544ddc2655
+  metadata.gz: 8b9ba73d3704dff23f9e5fc9d515a87ad2e822b7fd08aa9207e9e47d0e47e5ece4ba66bed8514e3465e87ddf761060ed73c2f6cfb8c79be7438a4f7ebe5452eb
+  data.tar.gz: eb6048d787fbc7f3001e2fe7b47b999e404282b801741c07248ee0a6516c64a24b8790f5093383aa5f816a902178752fd8f830977ba4ee55dc4fc36f5b7e4fdc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.1.1)
+    zero-rails_openapi (1.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,9 @@
 # ZRO: OpenApi 3 DocGenerator for Rails
 
-Provide concise DSL for you to generate the OpenAPI Specification 3 (**OAS3**, formerly Swagger3) JSON file for Rails application, 
+[![Gem Version](https://badge.fury.io/rb/zero-rails_openapi.svg)](https://badge.fury.io/rb/zero-rails_openapi)
+[![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
+
+Provide concise DSL for generating the OpenAPI Specification 3 (**OAS3**, formerly Swagger3) documentation JSON file for Rails application, 
 then you can use Swagger UI 3.2.0+ to show the documentation.
 
 ## Contributing
@@ -22,7 +25,9 @@ but I dont have enough time now = ▽ =
   - [Generate JSON Documentation File](#generate-json-documentation-file)
   - [Use Swagger UI(very beautiful web page) to show your Documentation](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
   - [Tricks](#tricks)
-    - [Write the DSL Somewhere Else](#write-the-dsl-somewhere-else)
+    - [Write DSL Somewhere Else](#trick1-write-the-dsl-somewhere-else)
+    - [DRYing](#trick2-drying)
+    - [Auto Generate Description](#trick3-auto-generate-description)
 - [Troubleshooting](#troubleshooting)
 
 ## About OAS
@@ -65,7 +70,7 @@ OpenApi.configure do |c|
   # [REQUIRED] The output location where .json doc file will be written to.
   c.file_output_path = 'public/open_api'
 
-  c.register_apis = {
+  c.register_docs = {
       homepage_api: {
           # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
           root_controller: Api::V1::BaseController,
@@ -89,7 +94,7 @@ end
 You can also set the *global configuration(/component)* of OAS: 
 Server Object / Security Scheme Object / Security Requirement Object ...
 
-For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/open_api.rb)
+For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
 
 ## Usage
 
@@ -108,17 +113,18 @@ class ApplicationController < ActionController::API
 
 #### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/examples_controller.rb)
 
+(TODO: I consider that, here should be put in a the simplest case.)
 ```ruby
 class Api::V1::ExamplesController < Api::V1::BaseController
   apis_set 'ExamplesController\'s APIs' do
-    schema :Dog           => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+    schema :Dog           => [ String, must_be: 'doge' ]
     query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
     path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
     resp   :RespComp      => [ 'bad request', :json ]
     body!  :RqBodyComp    => [ :form ]
   end
 
-  open_api_set %i[index show], 'common response' do
+  api_dry %i[index show], 'common response' do
     response '567', 'query result export', :pdf, type: File
   end
 
@@ -178,17 +184,17 @@ end
   desc and external_doc_url will be output to the tags[the current tag] (tag defaults to controller_name ), but are optional. 
   the focus is on the block, the DSL methods in the block will generate components.
 
-- `open_api_set` [Optional]
+- `api_dry` [Optional]
 
   this method is for DRYing.
   
   ```ruby
   # method signature
-  open_api_set method = :all, desc = '', &block
+  api_dry method = :all, desc = '', &block
   # usage
-  open_api_set :all, 'common response' do; end
-  open_api_set :index do; end
-  open_api_set [:index, :show] do; end
+  api_dry :all, 'common response' do; end
+  api_dry :index do; end
+  api_dry [:index, :show] do; end
   ```
   
   As you think, the DSL methods in the block will be executed to each API that you set by method.
@@ -205,7 +211,7 @@ end
   ```
 
 
-#### \>\> DSL methods inside *open_api* and *open_api_set*'s block ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: ApiInfoObj)
+#### \>\> DSL methods inside *open_api* and *api_dry*'s block ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: ApiInfoObj)
 
 These methods in the block describe the specified API(s): description, valid?,
 parameters, request body, responses, securities, servers.
@@ -237,6 +243,8 @@ parameters, request body, responses, securities, servers.
 
   You can of course describe the input in it's DSL method (like `query! :done` [this line](https://github.com/zhandao/zero-rails_openapi#-dsl-usage-example)), 
   but that will make it long and ugly. We recommend that unite descriptions in this place.
+  
+  In addition, when you want to dry the same parameters (each with a different description), it will be of great use.
 
 - param family methods (OAS - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject))
   - `param`
@@ -300,7 +308,21 @@ parameters, request body, responses, securities, servers.
   def form desc = '', schema_hash = { }
     body :form, desc, schema_hash
   end
+  # usage
+  form! 'register', data: {
+          name: String,
+          password: String,
+          password_confirmation: String
+      }
+  # advance usage
+  form 'for creating a user', data: {
+          :name! =>     { type: String, desc: 'user name' },
+          :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
+          # optional
+          :remarks =>   { type: String, desc: 'remarks' },
+      }
 
+  # method implement
   def file! media_type, desc = '', schema_hash = { type: File }
     body! media_type, desc, schema_hash
   end
@@ -371,9 +393,16 @@ The DSL methods used to generate the components in this block are:
   schema component_key, type, schema_hash
   # usage
   schema :Dog  => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+  # advance usage
+  schema :Dog => [{
+                       id!: Integer,
+                       name: { type: String, must_be: 'zhandao', desc: 'name' }
+                   }, # this is schema type*
+                   dft: { id: 1, name: 'pet' }]
   # or (unrecommended)
   schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
   ```
+  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
 
 ### Generate JSON Documentation File
 
@@ -395,9 +424,9 @@ In order to use it, you may have to enable CORS, [see](https://github.com/swagge
 
 ### Tricks
 
-#### Write the DSL Somewhere Else
+#### Trick1 - Write the DSL Somewhere Else
 
-Does your documentation take too mant lines?  
+Does your documentation take too many lines?  
 Do you want to separate documentation from business controller to simplify both?  
 Very easy! Just use `ctrl_path`.
 
@@ -425,6 +454,45 @@ end
 
 Notes: convention is the file name ends with `_doc.rb`
 
+#### Trick2 - DRYing
+
+To be written.
+
+You can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_dsl.rb) at the moment.  
+In general is to use method `api_dry`.
+The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
+
+#### Trick3 - Auto Generate Description
+
+```ruby
+desc 'api desc',
+     search_type!: 'search field, allows：<br/>'
+query :search_type, String, enum: %w[name creator category price]
+
+# or
+
+query :search_type, String, desc!: 'search field, allows：<br/>',
+      enum: %w[name creator category price]
+```
+
+Notice `!` use (`search_type!`, `desc!`), it tells ZRO to append
+information that analyzed from definitions (enum, must_be ..) to description automatically.
+
+Any one of above will generate:  
+`search field, allows：<br/>1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>`
+
+ZRO also allows you use Hash to define `enum`:
+```ruby
+query :view, String, enum: {
+        'all goods (default)': :all,
+        'only online':         :online,
+        'only offline':        :offline,
+        'expensive goods':     :get,
+        'cheap goods':         :borrow,
+    }
+```
+Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_desc.rb) to learn more.
+
 ## Troubleshooting
 
 - **You wrote document of the current API, but not find in the generated json file?**  

data/documentation/examples/auto_gen_desc.rb

@@ -0,0 +1,28 @@
+class V1::GoodsDoc < BaseDoc
+
+  open_api :index, 'Get list of Goods.' do
+    desc 'listing Goods',
+         view!: 'search view, allows:：<br/>',
+               # '1/ all goods (default)：all<br/>' \
+               # '2/ only online：online<br/>' \
+               # '3/ only offline：offline<br/>' \
+               # '4/ expensive goods：expensive<br/>' \
+               # '5/ cheap goods：cheap<br/>',
+         search_type!: 'search field, allows：<br/>'
+               # '1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>'
+
+    # query :view,        String, enum: %w[all online offline get borrow]
+    query :view, String, enum: {
+        'all goods (default)': :all,
+        'only online':         :online,
+        'only offline':        :offline,
+        'expensive goods':     :get,
+        'cheap goods':         :borrow,
+    }
+    query :search_type, String, enum: %w[name creator category price]
+    # Same as:
+    # query :search_type, String, desc!: 'search field, allows：<br/>',
+    #       enum: %w[name creator category price]
+  end
+
+end

data/documentation/examples/auto_gen_dsl.rb

@@ -0,0 +1,42 @@
+require 'open_api/generator'
+
+# Usage: add `include AutoGenDSL` to base controller.
+module AutoGenDSL
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def inherited(subclass)
+      super
+      subclass.class_eval do
+        break unless self.name.match? /sController|sDoc/
+        ctrl_path "api/#{self.name.sub('Doc', '').downcase.gsub('::', '/')}" if self.name.match? /sDoc/
+        open_api_dry
+      end
+    end
+
+    private
+
+    def open_api_dry
+      ctrl_path = try(:controller_path) || instance_variable_get('@_ctrl_path')
+      ::OpenApi::Generator.get_actions_by_ctrl_path(ctrl_path)&.each do |action|
+        api_dry action do
+          # Token in Header
+          if !action_path.match?(/NoVerificationController/) && !%w[create login].include?(action)
+            header! 'Token', String, desc: 'user token'
+          end
+
+          # Common :index parameters
+          if !action_path.match?(/NotDRYController/) && action == 'index'
+            query :page,     Integer, desc: 'page'
+            query :per_page, Integer, desc: 'per'
+          end
+
+          # OAS require at least one response on each api.
+          default_response 'default response', :json
+        end
+      end
+    end
+  end
+end

data/documentation/examples/examples_controller.rb

@@ -1,13 +1,18 @@
 class Api::V1::ExamplesController < Api::V1::BaseController
   apis_set 'ExamplesController\'s APIs' do
-    schema :Dog           => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+    schema :Dog => [{
+                         id!: Integer,
+                         name: { type: String, must_be: 'zhandao', desc: 'name' }
+                     }, # this is schema type, see:
+                     dft: { id: 1, name: 'pet' }]
+    # schema :Dog         => [ String, dft: { id: 1, name: 'pet' } ]
     query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
     path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
     resp   :RespComp      => [ 'bad request', :json ]
     body!  :RqBodyComp    => [ :form ]
   end
 
-  open_api_set %i[index show], 'common response' do
+  api_dry %i[index show], 'common response' do
     response '567', 'query result export', :pdf, type: File
   end
 
@@ -21,7 +26,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     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
@@ -33,4 +38,13 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     param_ref    :PathCompId, :QueryCompUuid
     response_ref '123' => :RespComp, '223' => :RespComp
   end
+
+  open_api :create do
+    form 'for creating a user', data: {
+        :name! =>     { type: String, desc: 'user name' },
+        :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
+        # optional
+        :remarks =>   { type: String, desc: 'remarks' },
+    }
+  end
 end

data/documentation/examples/open_api.rb

@@ -6,7 +6,7 @@ OpenApi.configure do |c|
 
   # 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 = {
+  c.register_docs = {
       homepage_api: {
           # [REQUIRED] ZRO will scan all the descendants of the root_controller, then generate their docs.
           root_controller: Api::V1::BaseController,
@@ -54,11 +54,11 @@ OpenApi.configure do |c|
                   # 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',
+                  url: 'http://localhost:3000',
                   # An optional string describing the host designated by the URL.
                   description: 'Optional server description, e.g. Main (production) server'
               },{
-                  url: 'http://localhost:3332',
+                  url: 'http://localhost:3001',
                   description: 'Optional server description, e.g. Internal staging server for testing'
               }
           ],

data/documentation/parameter.md

@@ -1,12 +1,15 @@
 ### More Explanation of Param() 
 
-- [param_type] OpenAPI 3.0 distinguishes between the following parameter types based on the parameter location: 
+#### param_type
+OpenAPI 3.0 distinguishes between the following parameter types based on the parameter location: 
 **header, path, query, cookie**. [more](https://swagger.io/docs/specification/describing-parameters/)
 
-- [name] parameter name. If param_type is :path, it must correspond to the associated path segment form 
+#### name
+parameter name. If param_type is :path, it must correspond to the associated path segment form 
 the routing path, for example: the path is `/good/:id`, then you have to declare a path parameter with name `id`.
 
-- [type] parameter (schema) type. Support all [data types](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#dataTypes) defined in OAS.   
+#### type
+parameter (schema) type. Support all [data types](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#dataTypes) defined in OAS.   
 In addition, you can use `format` in schema_hash to define in fine detail the data type being used, like: 
 int32, float, date ...  
 All the types you can use are:
@@ -27,22 +30,25 @@ All the types you can use are:
   You can use `Object.const_set()` to define a constant that does not exist, but note that 
   the value you set could not be a Symbol (it will be explained as a Ref Object), should be a String.
 
-- [required] :opt or :req
+#### required
+ :opt or :req
 
-- The [[schema]](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#schemaObject) defining the type used for the parameter. 
+#### Schema Hash
+
+The [[schema]](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#schemaObject) defining the type used for the parameter. 
 schema_hash(optional) will be used to generate Schema Object inside Parameter Object.  
 [source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/oas_objs/schema_obj.rb)  
 You can set the schema by following keys (all are optional), the words in parentheses are available aliases of the keys:  
-  - enum (values, allowable_values)  
+  - **enum (values, allowable_values)**  
   Must be Array or Range(will be converted to Array)
-  - value (must_be, allowable_value)  
+  - **must_be (value, allowable_value)**  
   Single value, could be a String, Array ...  
-  - range (number_range)  
+  - **range (number_range)**  
   Allow value in this continuous range. Set this field like this: `{ gt: 0, le: 5 }`
-  - length (lth)  
+  - **length (lth)**  
   Must be an Integer, Integer Array, Integer Range, or the following format Symbol: `:gt_`, `:ge_`, `:lt_`, `:le_`, examples: :ge_5 means "greater than or equal 5"; :lt_9 means "lower than 9".
-  - format (fmt)
-  - is (is_a)  
+  - **format (fmt)**
+  - **is (is_a)**  
     1. It's not in OAS, just an addition field for better express.You can see it as `format`, but in fact they are quite different.  
     2. Look at this example: the `format` is set to "int32", but you also want to express that this 
     schema is an "id" format —— this cannot be expressed in the current OAS version.  
@@ -51,5 +57,5 @@ You can set the schema by following keys (all are optional), the words in parent
     for example the parameter name "user_email" will generate "is: email". Default `is` options are:  
     [email phone password uuid uri url time date], to overwrite it you can set it in initializer `c.is_options = %w[]`.
     5. If type is Object, for describing each property's schema, the only way is use ref type, like: `{ id: :Id, name: :Name }`
-  - pattern (regexp, pr, reg)
-  - default (dft, default_value)
+  - **pattern (regexp, pr, reg)**
+  - **default (dft, default_value)**

data/lib/oas_objs/helpers.rb

@@ -7,22 +7,22 @@ module OpenApi
     end
 
     def value_present
-      Proc.new { |_, v| truly_present? v }
+      proc { |_, v| truly_present? v }
     end
 
     def assign(value)
-      @assign = value.is_a?(Symbol)? self.send("_#{value}") : value
+      @assign = value.is_a?(Symbol) ? send("_#{value}") : value
       self
     end
 
-    def all(*values)
+    def reduceee(*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)
+        send("#{who}=", @assign)
       else
         processed[who.to_sym] = @assign
       end if truly_present?(@assign)
@@ -34,7 +34,7 @@ module OpenApi
       self[who.to_sym] = @assign if truly_present?(@assign)
     end
 
-    def for_merge # to_processed
+    def then_merge! # to_processed
       processed.tap { |it| it.merge! @assign if truly_present?(@assign) }
     end
   end

data/lib/oas_objs/media_type_obj.rb

@@ -7,13 +7,13 @@ module OpenApi
       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)
+        self.schema     = SchemaObj.new(schema_hash[:type] || schema_hash[:data], schema_hash)
       end
 
       def process
-        schema_processed = self.schema.process
+        schema_processed = schema.process
         schema = schema_processed.values.join.blank? ? { } : { schema: schema_processed }
-        media_type.nil? ? { } : { media_type =>  schema }
+        media_type.nil? ? { } : { media_type => schema }
       end
 
       # https://swagger.io/docs/specification/media-types/
@@ -23,32 +23,32 @@ module OpenApi
       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
+        when :app then   'application/*'
+        when :json then  'application/json'
+        when :xml then   'application/xml'
+        when :xwww then  'application/x-www-form-urlencoded'
+        when :pdf then   'application/pdf'
+        when :zip then   'application/zip'
+        when :gzip then  'application/gzip'
+        when :doc then   'application/msword'
+        when :docx then  'application/application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+        when :xls then   'application/vnd.ms-excel'
+        when :xlsx then  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+        when :ppt then   'application/vnd.ms-powerpoint'
+        when :pptx then  'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+        # when :pdf then   'application/pdf'
+        when :form then  'multipart/form-data'; when :form_data then 'multipart/form-data'
+        when :text then  'text/*'
+        when :plain then 'text/plain then charset=utf-8'
+        when :html then  'text/html'
+        when :csv then   'text/csv'
+        when :image then 'image/*'
+        when :png then   'image/png'
+        when :jpeg then  'image/jpeg'
+        when :gif then   'image/gif'
+        when :audio then 'audio/*'
+        when :video then 'video/*'
+        else             nil
         end
       end
     end

data/lib/oas_objs/param_obj.rb

@@ -11,15 +11,23 @@ module OpenApi
         self.processed = {
             name: name,
             in: param_type,
-            required: "#{required}".match?(/req/),
+            required: required.to_s.match?(/req/),
         }
         self.schema = SchemaObj.new(type, schema_hash)
-        self.merge! schema_hash
+        merge! schema_hash
       end
 
       def process
-        assign(_desc).to_processed 'description'
-        processed.tap { |it| it[:schema] = schema.process_for self[:name] }
+        assign(desc).to_processed 'description'
+        processed.tap { |it| it[:schema] = schema.process_for self.processed[:name] }
+      end
+
+      def desc
+        if __desc.present?
+          schema.preprocess_with_desc __desc, self[:name]
+        else
+          _desc
+        end
       end
 
 
@@ -27,9 +35,10 @@ module OpenApi
       # 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 ],
+          _range:  %i[ range   number_range ],
+          _length: %i[ length  lth          ],
+          _desc:   %i[ desc    description  ],
+          __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?

data/lib/oas_objs/ref_obj.rb

@@ -10,7 +10,7 @@ module OpenApi
       attr_accessor :processed
       def initialize(ref_to, component_key)
         self.processed = {
-            '$ref': "#components/#{ref_to}s/#{component_key}"
+            '$ref': "#components/#{ref_to.to_s.pluralize}/#{component_key}"
         }
       end
 

data/lib/oas_objs/request_body_obj.rb

@@ -11,7 +11,7 @@ module OpenApi
       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 }
+        self.processed  = { required: required.to_s.match?(/req/), description: desc }
       end
 
       def process
@@ -31,7 +31,7 @@ A request body with a referenced model definition.
 {
   "description": "user to add to the system",
   "content": {
-    "application/json": {
+    "multipart/form-data": {
       "schema": {
         "$ref": "#/components/schemas/User"
       },

data/lib/oas_objs/response_obj.rb

@@ -9,7 +9,7 @@ module OpenApi
 
       attr_accessor :processed, :code, :media_type
       def initialize(code, desc, media_type, schema_hash)
-        self.code       = "#{code}"
+        self.code       = code.to_s
         self.media_type = MediaTypeObj.new(media_type, schema_hash)
         self.processed  = { description: desc }
       end

data/lib/oas_objs/schema_obj.rb

@@ -18,25 +18,66 @@ module OpenApi
         #        However, user can decide how to write --
         #          `type: number, format: double`, or `type: double`
         self.type = type
-        self.merge! schema_hash
+        merge! schema_hash
       end
 
 
-      def process_for(param_name = nil)
+      def process_for(param_name = nil, options = { desc_inside: false })
+        return processed if @preprocessed
+
         processed.merge! processed_type
-        all(processed_enum_and_length,
-            processed_range,
-            processed_is_and_format(param_name),
-            { pattern: _pattern&.inspect&.delete('/'),
-              default: _default }
-        ).for_merge
+        reduceee processed_enum_and_length,
+                 processed_range,
+                 processed_is_and_format(param_name),
+                 {
+                     pattern: _pattern&.inspect&.delete('/'),
+                     default: _default,
+                 }
+        then_merge!
+
+        assign(processed_desc options).then_merge!
       end
       alias_method :process, :process_for
 
+      def preprocess_with_desc desc, param_name = nil
+        self.__desc = desc
+        process_for param_name
+        @preprocessed = true
+        __desc
+      end
+
+      def processed_desc(options)
+        result = __desc ? self.__desc = process_desc : _desc
+        options[:desc_inside] ? { description: result } : nil
+      end
+
+      def process_desc
+        if processed[:enum].present?
+          if @enum_info.present?
+            @enum_info.each_with_index do |(info, value), index|
+              __desc.concat "#{index + 1}/ #{info}: #{value}<br/>"
+            end
+          else
+            processed[:enum].each_with_index do |value, index|
+              __desc.concat "#{index + 1}/ #{value}<br/>"
+            end
+          end
+        end
+        __desc
+      end
+
       def processed_type(type = self.type)
         t = type.class.in?([Hash, Array, Symbol]) ? type : "#{type}".downcase
         if t.is_a? Hash
-          recursive_obj_type t
+          # For support writing:
+          #   form 'desc', data: {
+          #     id!: { type: Integer, enum: 0..5, desc: 'user id' }
+          # }
+          if t.key? :type
+            SchemaObj.new(t[:type], t).process_for @prop_name, desc_inside: true
+          else
+            recursive_obj_type t
+          end
         elsif t.is_a? Array
           recursive_array_type t
         elsif t.is_a? Symbol
@@ -47,12 +88,14 @@ module OpenApi
           { type: 'string', format: t}
         elsif t.eql? 'file'
           { type: 'string', format: OpenApi.config.dft_file_format }
+        elsif t.eql? 'datetime'
+          { type: 'string', format: 'date-time' }
         else # other string
           { type: t }
         end
       end
       def recursive_obj_type(t) # DSL use { prop_name: prop_type } to represent object structure
-        return processed_type(t) unless t.is_a? Hash
+        return processed_type(t) if !t.is_a?(Hash) || t.key?(:type)
 
         _schema = {
             type: 'object',
@@ -60,6 +103,7 @@ module OpenApi
             required: [ ]
         }
         t.each do |prop_name, prop_type|
+          @prop_name = prop_name
           _schema[:required] << "#{prop_name}".delete('!') if "#{prop_name}".match? '!'
           _schema[:properties]["#{prop_name}".delete('!').to_sym] = recursive_obj_type prop_type
         end
@@ -78,6 +122,16 @@ module OpenApi
       end
 
       def processed_enum_and_length
+        # Support this writing for auto generating desc from enum.
+        #   enum: {
+        #     'all_data': :all,
+        #     'one_page': :one
+        # }
+        if _enum.is_a? Hash
+          @enum_info = _enum
+          self._enum = _enum.values
+        end
+
         %i[_enum _length].each do |key|
           value = self.send(key)
           self[key] = value.to_a if value.present? && value.is_a?(Range)
@@ -85,7 +139,7 @@ module OpenApi
 
         # generate_enums_by_enum_array
         values = _enum || _value
-        self._enum = (values.is_a?(Array) ? values : [values]) if truly_present?(values)
+        self._enum = Array(values) if truly_present?(values)
 
         # generate length range fields by _lth array
         lth = _length || [ ]
@@ -124,21 +178,23 @@ module OpenApi
       def recognize_is_options_in(name)
         # identify whether `is` patterns matched the name, if so, generate `is`.
         OpenApi.config.is_options.each do |pattern|
-          self._is = pattern or break if "#{name}".match? /#{pattern}/
+          self._is = pattern or break if name.match? /#{pattern}/
         end if _is.nil?
         self.delete :_is if _is.in?([:x, :we])
       end
 
 
       { # SELF_MAPPING
-        _enum:    %i[enum     values  allowable_values],
-        _value:   %i[must_be  value   allowable_value ],
-        _range:   %i[range    number_range            ],
-        _length:  %i[length   lth                     ],
-        _is:      %i[is_a     is                      ], # NOT OAS Spec, just an addition
-        _format:  %i[format   fmt                     ],
-        _pattern: %i[pattern  regexp  pr   reg        ],
-        _default: %i[default  dft     default_value   ],
+          _enum:    %i[ enum     values  allowable_values ],
+          _value:   %i[ must_be  value   allowable_value  ],
+          _range:   %i[ range    number_range             ],
+          _length:  %i[ length   lth                      ],
+          _is:      %i[ is_a     is                       ], # NOT OAS Spec, just an addition
+          _format:  %i[ format   fmt                      ],
+          _pattern: %i[ pattern  regexp  pr   reg         ],
+          _default: %i[ default  dft     default_value    ],
+          _desc:    %i[ desc     description              ],
+          __desc:   %i[ desc!    description!             ],
       }.each do |key, aliases|
         define_method key do
           aliases.each do |alias_name|

data/lib/open_api/config.rb

@@ -7,7 +7,7 @@ module OpenApi
     DEFAULT_CONFIG = {
         is_options: %w[email phone password uuid uri url time date],
         dft_file_format: 'binary'
-    }
+    }.freeze
 
     module ClassMethods
       def config
@@ -19,15 +19,15 @@ module OpenApi
       end
 
       ### config options
-      # register_apis = {
-      #     version: {
+      # register_docs = {
+      #     doc_name: {
       #         :file_output_path, :root_controller
       #         info: {}
       #     }}
       # is_options = %w[]
 
       def apis
-        @apis ||= @config.register_apis
+        @apis ||= @config.register_docs
       end
     end
   end

data/lib/open_api/dsl.rb

@@ -29,24 +29,29 @@ module OpenApi
 
         # select the routing info (corresponding to the current method) from the routing list.
         action_path = "#{@_ctrl_path ||= controller_path}##{method}"
-        routes_info = ctrl_routes_list.select { |api| api[:action_path].match? /^#{action_path}$/ }.first
+        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match? /^#{action_path}$/ }&.first
         puts "[zero-rails_openapi] Routing mapping failed: #{@_ctrl_path}##{method}" or return if routes_info.nil?
 
         # structural { path: { http_method:{ } } }, for Paths Object.
         path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
         current_api = path[routes_info[:http_verb]] =
-            ApiInfoObj.new(action_path).merge! summary: summary, operationId: method, tags: [@_apis_tag]
+            ApiInfoObj.new(action_path)
+                .merge! description: '', summary: summary, operationId: method, tags: [@_apis_tag],
+                        parameters: [ ], requestBody: '', responses: { },
+                        security: [ ], servers: [ ]
 
         current_api.tap do |it|
-          it.instance_eval &block if block_given?
           [method, :all].each do |key| # blocks_store_key
             @_apis_blocks&.[](key)&.each { |blk| it.instance_eval &blk }
           end
+          it.instance_eval &block if block_given?
+          it.instance_eval { process_params }
+          it.delete_if { |_, v| v.blank? }
         end
       end
 
       # For DRY; method could be symbol array
-      def open_api_set method = :all, desc = '', &block
+      def api_dry method = :all, desc = '', &block
         @_apis_blocks ||= { }
         if method.is_a? Array
           method.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }

data/lib/open_api/dsl_inside_block.rb

@@ -8,7 +8,7 @@ module OpenApi
   module DSL
     module CommonDSL
       def arrow_writing_support
-        Proc.new do |args, executor|
+        proc do |args, executor|
           if args.count == 1 && args.first.is_a?(Hash)
             send(executor, args[0].keys.first, *args[0].values.first)
           else
@@ -45,9 +45,9 @@ module OpenApi
       end
 
       { # alias_methods mapping
-        response:         %i[error_response  resp                     ],
-        default_response: %i[dft_resp        dft_response             ],
-        error_response:   %i[other_response  oth_resp  error  err_resp],
+          response:         %i[ error_response  resp                      ],
+          default_response: %i[ dft_resp        dft_response              ],
+          error_response:   %i[ other_response  oth_resp  error  err_resp ],
       }.each do |original_name, aliases|
         aliases.each do |alias_name|
           alias_method alias_name, original_name
@@ -61,7 +61,7 @@ module OpenApi
     class CtrlInfoObj < Hash
       include DSL::CommonDSL
 
-      def _schema component_key, type, schema_hash
+      def _schema component_key, type, schema_hash = { }
         (self[:schemas] ||= { }).merge! component_key => SchemaObj.new(type, schema_hash).process
       end
       def schema *args
@@ -115,12 +115,42 @@ module OpenApi
 
       def desc desc, inputs_descs = { }
         @inputs_descs = inputs_descs
+        merge_desc_for_dryed_param
         self[:description] = desc
       end
 
+      # TODO: HACK
+      def merge_desc_for_dryed_param
+        @inputs_descs.each do |param_name, desc|
+          self[:parameters].each do |param|
+            if param_name.match?(?!) && param.processed[:name].to_s == param_name.to_s.delete(?!)
+              param.merge!(desc!: desc).process
+            end
+          end
+        end
+      end
+
       def param param_type, name, type, required, schema_hash = { }
-        schema_hash[:desc] = @inputs_descs[name] if @inputs_descs&.[](name).present?
-        (self[:parameters] ||= [ ]) << ParamObj.new(name, param_type, type, required, schema_hash).process
+        if @inputs_descs&.[](name).present?
+          schema_hash[:desc] = @inputs_descs[name]
+        elsif @inputs_descs&.[]("#{name}!".to_sym).present?
+          schema_hash[:desc!] = @inputs_descs["#{name}!".to_sym]
+        end
+
+        param_obj = ParamObj.new(name, param_type, type, required, schema_hash)
+        # The definition of the same name parameter will be overwritten
+        index = self[:parameters].map { |p_obj| p_obj.processed[:name] }.index name
+        if index.present?
+          self[:parameters][index] = param_obj
+        else
+          self[:parameters] << param_obj
+        end
+      end
+
+      def process_params
+        self[:parameters].each_with_index do |param_obj, index|
+          self[:parameters][index] = param_obj.process
+        end
       end
 
       def _param_agent name, type, schema_hash = { }
@@ -128,7 +158,7 @@ module OpenApi
       end
 
       def param_ref component_key, *keys
-        (self[:parameters] ||= [ ]).concat [component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process }
+        self[:parameters].concat [component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process }
       end
 
       def request_body required, media_type, desc = '', schema_hash = { }
@@ -140,16 +170,16 @@ module OpenApi
       end
 
       def body_ref component_key
-        self[:requestBody] = RefObj.new(:parameter, component_key).process
+        self[:requestBody] = RefObj.new(:requestBody, component_key).process
       end
 
       def response_ref code_compkey_hash
         code_compkey_hash.each do |code, component_key|
-          (self[:responses] ||= { }).merge! code => RefObj.new(:response, component_key).process
+          self[:responses].merge! code => RefObj.new(:response, component_key).process
         end
       end
 
-      # 注意同时只能写一句 request body，包括 form 和 file
+      # TODO: 目前只能写一句 request body，包括 form 和 file， 需要同时支持一下扁平化
       def form desc = '', schema_hash = { }
         body :form, desc, schema_hash
       end
@@ -164,11 +194,11 @@ module OpenApi
       end
 
       def security scheme_name, requirements = [ ]
-        (self[:security] ||= [ ]) << { scheme_name => requirements }
+        self[:security] << { scheme_name => requirements }
       end
 
       def server url, desc
-        (self[:servers] ||= [ ]) << { url: url, description: desc }
+        self[:servers] << { url: url, description: desc }
       end
     end # ----------------------------------------- end of ApiInfoObj
   end

data/lib/open_api/generator.rb

@@ -1,5 +1,3 @@
-require 'active_support/hash_with_indifferent_access'
-
 module OpenApi
   module Generator
     def self.included(base)
@@ -9,33 +7,35 @@ module OpenApi
     module ClassMethods
       def generate_docs(api_name = nil)
         Dir['./app/controllers/**/*.rb'].each { |file| require file }
+        # TODO: _doc should be configured
         Dir['./app/**/*_doc.rb'].each { |file| require file }
         if api_name.present?
           [{ api_name => generate_doc(api_name) }]
         else
-          OpenApi.apis.keys.map { |api_key| { api_key => generate_doc(api_key)} }.reduce({ }, :merge)
+          OpenApi.apis.keys.map { |api_key| { api_key => generate_doc(api_key) } }.reduce({ }, :merge)
         end
       end
 
       def generate_doc(api_name)
         settings = OpenApi.apis[api_name]
-        doc = { openapi: '3.0.0' }.merge(settings.slice :info, :servers).merge({
+        doc = { openapi: '3.0.0' }.merge(settings.slice :info, :servers).merge(
                 security: settings[:global_security], tags: [ ], paths: { },
                 components: {
                     securitySchemes: settings[:global_security_schemes],
                     schemas: { }
                 }
-              })
+              )
 
         settings[:root_controller].descendants.each do |ctrl|
           ctrl_infos = ctrl.instance_variable_get('@_ctrl_infos')
           next if ctrl_infos.nil?
-          doc[:paths].merge! ctrl.instance_variable_get('@_api_infos')
+          doc[:paths].merge! ctrl.instance_variable_get('@_api_infos') || { }
           doc[:tags] << ctrl_infos[:tag]
-          doc[:components].merge! ctrl_infos[:components]
+          doc[:components].merge! ctrl_infos[:components] || { }
         end
-        doc[:components].delete_if { |_,v| v.blank? }
-        ($open_apis ||= { })[api_name] ||= HashWithIndifferentAccess.new(doc.delete_if { |_,v| v.blank? })
+        doc[:components].delete_if { |_, v| v.blank? }
+        ($open_apis ||= { })[api_name] ||=
+            ActiveSupport::HashWithIndifferentAccess.new(doc.delete_if { |_, v| v.blank? })
       end
 
       def write_docs
@@ -64,13 +64,13 @@ module OpenApi
                     item.match?(/:/) ? "{#{item[1..-1]}}" : item
                   end.join('/'),          # => "/api/v1/examples/{id}"
             action_path: infos[2]         # => "api/v1/examples#index"
-        }
-      end.group_by {|api| api[:action_path].split('#').first } # => { "api/v1/examples" => [..] }, group by paths
+        } rescue next
+      end.compact.group_by {|api| api[:action_path].split('#').first } # => { "api/v1/examples" => [..] }, group by paths
     end
 
     def self.get_actions_by_ctrl_path(path)
       @routes_list ||= generate_routes_list
-      @routes_list[path].map do |action_info|
+      @routes_list[path]&.map do |action_info|
         action_info[:action_path].split('#').last
       end
     end

data/lib/open_api/version.rb

@@ -1,3 +1,3 @@
 module OpenApi
-  VERSION = '1.1.1'
+  VERSION = '1.2.0'
 end

data/zero-rails_openapi.gemspec

@@ -9,9 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ["zhandao"]
   spec.email         = ["x@skippingcat.com"]
 
-  spec.summary       = %q{Generate the OpenAPI Specification JSON file for Rails application.}
-  spec.description   = %q{Provide concise DSL for you to generate the OpenAPI Specification 3 (Swagger 3)
-                         JSON file for Rails application, then you can use Swagger-UI 3.2.0+ to show the documentation.}
+  spec.summary       = %q{Generate the OpenAPI Specification 3 documentation for Rails application.}
+  spec.description   = %q{Provide concise DSL for generating the OpenAPI Specification 3 (OAS3)
+                         documentation JSON file for Rails application,
+                         then you can use Swagger-UI 3.2.0+ to show the documentation.}
   spec.homepage      = "https://github.com/zhandao/zero-rails_openapi"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-30 00:00:00.000000000 Z
+date: 2017-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,8 +53,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: |-
-  Provide concise DSL for you to generate the OpenAPI Specification 3 (Swagger 3)
-                           JSON file for Rails application, then you can use Swagger-UI 3.2.0+ to show the documentation.
+  Provide concise DSL for generating the OpenAPI Specification 3 (OAS3)
+                           documentation JSON file for Rails application,
+                           then you can use Swagger-UI 3.2.0+ to show the documentation.
 email:
 - x@skippingcat.com
 executables: []
@@ -73,6 +74,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- documentation/examples/auto_gen_desc.rb
+- documentation/examples/auto_gen_dsl.rb
 - documentation/examples/examples_controller.rb
 - documentation/examples/open_api.rb
 - documentation/parameter.md
@@ -89,7 +92,6 @@ files:
 - lib/open_api/dsl_inside_block.rb
 - lib/open_api/generator.rb
 - lib/open_api/version.rb
-- lib/takes/open_api.rake
 - zero-rails_openapi.gemspec
 homepage: https://github.com/zhandao/zero-rails_openapi
 licenses:
@@ -111,8 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: Generate the OpenAPI Specification JSON file for Rails application.
+summary: Generate the OpenAPI Specification 3 documentation for Rails application.
 test_files: []

data/lib/takes/open_api.rake

@@ -1,6 +0,0 @@
-namespace :openapi do
-  desc 'Generate OpenApi documentation files'
-  task :api => [:environment] do |t, args|
-    OpenApi.write_docs
-  end
-end