zero-rails_openapi 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 388bb78c95e92399dacc43b0a83ae3b5165e3ea2
-  data.tar.gz: 352a5d7fdf9f6aa670a7e0ea56a99934dec0375c
+  metadata.gz: 4b90e9497b858c621362ea5413020a64bdbd59de
+  data.tar.gz: '067410229fdc842e1d2f65e3cf4fbb9482535044'
 SHA512:
-  metadata.gz: 26b8d36f4601facd4ed6936e5be617a8cc03ee279c99c603727ad7fb7432841f2e9ad20691e1d1a0f6e448a837b758f55cf5e4408027b87cc25ce3bd7391a0c4
-  data.tar.gz: bbfc3c14e4c72b8f56eed5dae4fb4df9c5120e81bd1c7d8a4fd535c0853a7e23d018812aabfa3283d51b421b8a8aee6d3ab84ef055087dbf6c418c5a1bb4a82d
+  metadata.gz: eefc1f9b19e39b1a7aee1f9817c9860da02b77f4feb94a22a72fa8dd11739e9e9b1cda3d23404bfeaefbeba9fd3a9cd2c06898f92a31f14c60eae3c1788b5b61
+  data.tar.gz: 1d5bf3b31a7e8ed246e50ecd63f869c0913185a0eb31c95490d32163f48ff5c0eba8e744ce4ec234ad72ff8821e3f246b515d0cec473cb3d4269eaf9c8bf11f5

data/Gemfile

@@ -3,4 +3,4 @@ source "https://rubygems.org"
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in zero-rails_openapi.gemspec
-gemspec
+gemspec

data/Gemfile.lock

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

data/README.md

@@ -1,7 +1,29 @@
 # 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, 
-then you can use Swagger-UI 3.2.0+ to show the documentation.
+then you can use Swagger UI 3.2.0+ to show the documentation.
+
+## Contributing
+
+**Hi, here is ZhanDao. This gem was completed when I learned Ruby less than three months, 
+I'm not sure if it has problem, but it may have a lot to improve.  
+I'm looking forward to your issues and PRs, thanks!**
+
+Currently, I think the most important TODO is the Unit Test (RSpec, I want is), 
+but I dont have enough time now = ▽ =
+
+## Table of Contents
+
+- [About OAS](https://github.com/zhandao/zero-rails_openapi#about-oas) (OpenAPI Specification)
+- [Installation](https://github.com/zhandao/zero-rails_openapi#installation)
+- [Configure](https://github.com/zhandao/zero-rails_openapi#configure)
+- [Usage](https://github.com/zhandao/zero-rails_openapi#usage)
+  - [DSL for documenting your controller](https://github.com/zhandao/zero-rails_openapi#dsl-for-documenting-your-controller)
+  - [Generate JSON Documentation File](https://github.com/zhandao/zero-rails_openapi#generate-json-documentation-file)
+  - [Use Swagger UI(very beautiful web page) to show your Documentation](https://github.com/zhandao/zero-rails_openapi#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
+  - [Tricks](#tricks)
+    - [Write the DSL Somewhere Else]
+- [Troubleshooting](https://github.com/zhandao/zero-rails_openapi#troubleshooting)
 
 ## About OAS
 
@@ -45,7 +67,7 @@ OpenApi.configure do |c|
 
   c.register_apis = {
       homepage_api: {
-          # [REQUIRED] ZRO will scan all the descendants of the root_controller, then generate their docs.
+          # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
           root_controller: Api::V1::BaseController,
 
           # [REQUIRED] OAS Info Object: The section contains API information.
@@ -67,7 +89,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/master/lib/examples/open_api.rb)
+For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/open_api.rb)
 
 ## Usage
 
@@ -84,16 +106,16 @@ class ApplicationController < ActionController::API
  end
 ```
 
-#### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/examples/examples_controller.rb)
+#### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/examples_controller.rb)
 
 ```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' } ]
+    query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
     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 ]
+    body!  :RqBodyComp    => [ :form ]
   end
 
   open_api_set %i[index show], 'common response' do
@@ -128,71 +150,202 @@ end
 
 #### \> Explanation
 
-##### \>\> controller class methods ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl.rb))
+#### \>\> controller class methods ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl.rb))
 
-- `apis_set` [Optional]
+- `ctrl_path` (controller path) [Optional]
 
+  ```ruby
+  # method signature
+  ctrl_path path
+  # usage
+  ctrl_path 'api/v1/examples'
+  ```
+  This option allows you to set the Tag* (which is a node of [OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#openapi-object)).  
+  [Here's a trick](): Using `ctrl_path`, you can write the DSL somewhere else 
+  to simplify the current controller.  
+  \* Take the tag from `path.split('/').last`
 
+- `apis_set` [Optional]
+
+  ```ruby
+  # method signature
+  apis_set desc = '', external_doc_url = '', &block
+  # usage
+  apis_set 'ExamplesController\'s APIs' do
+    # DSL for defining components
+  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]
 
+  this method is for DRYing.
+  
+  ```ruby
+  # method signature
+  open_api_set 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
+  ```
+  
+  As you think, the DSL methods in the block will be executed to each API that you set by method.
+  
+- `open_api` [Required]
+
+  Define the specified API (in the following example is index).
+  
+  ```ruby
+  # method signature
+  open_api method, summary = '', &block
+  # usage
+  open_api :index, '(SUMMARY) this api blah blah ...' do; end
+  ```
 
-- `open_api`
 
-##### \>\> DSL methods inside *open_api* and *open_api_set*'s block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb)# ApiInfoObj )
+#### \>\> 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)
 
 These methods in the block describe the specified API(s): description, valid?,
 parameters, request body, responses, securities, servers.
 
+(Here corresponds to OAS [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#operationObject))
+
 - `this_api_is_invalid!`, its aliases are:
   - `this_api_is_expired!`
   - `this_api_is_unused!`
   - `this_api_is_under_repair!`
 
-```ruby
-    # method signature
-    this_api_is_invalid! explain = ''
-    # usage
-    this_api_is_invalid! 'this api is expired!'
-```
+  ```ruby
+  # method signature
+  this_api_is_invalid! explain = ''
+  # usage
+  this_api_is_invalid! 'this api is expired!'
+  ```
 
 - `desc`: description for current API and its inputs (parameters and request body)
 
-```ruby
-    # method signature
-    desc desc, inputs_descs = { }
-    # usage
-    desc 'current API\'s description',
-         id:         'user id',
-         email_addr: 'email_addr\'s desc'
-```
+  ```ruby
+  # method signature
+  desc desc, inputs_descs = { }
+  # usage
+  desc 'current API\'s description',
+       id:         'user id',
+       email_addr: 'email_addr\'s desc'
+  ```
 
-You can of course describe the input in it's DSL method (like `query! :done` this line), 
-but that will make it long and ugly. We recommend that unite descriptions in this place.
+  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.
 
-- param family methods
+- param family methods (OAS - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject))
   - `param`
   - `param_ref`
-  - `header`, `path`, `query`, `cookie`
-  - bang methods: `header!`, `path!`, `query!`, `cookie!`
+  - `header`, `path`, `query`, `cookie` and bang methods: `header!`, `path!`, `query!`, `cookie!`  
+  **The bang method(`!`) means it is required, so it is optional without `!`, the same below.**
+
+  Define the parameters for the API(operation).
+  You can use the Reference Object to link to parameters that are defined at the components/parameters by method param_ref().
+
+  ```ruby
+  # method signature
+  param param_type, name, type, required, schema_hash = { }
+  # usage
+  param :query,    :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page'
   
+  # method signature
+  param_ref component_key, *component_keys
+  # usage
+  param_ref :PathCompId
+  param_ref :PathCompId, :QueryCompUuid, ...
   
-- request_body family methods
+  # method signature
+  header  name, type, schema_hash = { }
+  header! name, type, schema_hash = { }
+  query!  name, type, schema_hash = { }
+  # usage
+  header! :'X-Token', String
+  query!  :done,      Boolean, must_be: false, default: true
+  ```
+
+  [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
+
+- request_body family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
   - `request_body`
   - `body_ref`
   - `body` and bang `body!`
+  - `form`, `form!`; `file`, `file!`
+  
+  OpenAPI 3.0 uses the requestBody keyword to distinguish the payload from parameters.  
+  Define the request body for the API(operation).
+  You can use the Reference Object to link to request body that is defined at the components/requestBodies by method body_ref().
+  
+  ```ruby
+  # method signature
+  request_body required, media_type, desc = '', schema_hash = { }
+  # usage
+  request_body :opt, :form, type: { id!: Integer, name: String }
+
+  # method signature
+  body_ref component_key
+  # usage
+  body_ref :Body
+
+  # method signature
+  body(!) media_type, desc = '', schema_hash = { }
+  # usage
+  body :json
+  
+  # method implement
+  def form desc = '', schema_hash = { }
+    body :form, desc, schema_hash
+  end
+
+  def file! media_type, desc = '', schema_hash = { type: File }
+    body! media_type, desc, schema_hash
+  end
+  ```
   
+  **Notice:** Each API can only declare a request body. 
+  That is, all of the above methods you can only choose one of them.
   
-- response family methods
+  Media Type: We provide some [mapping](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
+  
+  schema_hash: As above (see param), but more than a `type` (schema type).
+  
+- response family methods (OAS - [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#response-object))
   - `response` (`resp`)
   - `response_ref`
   - `default_response` (`dft_resp`)
-  - `error_response` (`other_response`, `oth_resp`, `error`, `err_resp`)
+  - `error_response` (`other_response`, `oth_resp`, `error`, `err_resp`): Are `response`'s aliases, should be used in the error response context.
+  
+  Define the responses for the API(operation).
+  You can use the Response Object to link to request body that is defined at the components/responses by method response_ref().
+  
+  ```ruby
+  # method signature
+  response code, desc, media_type = nil, schema_hash = { }
+  # usage
+  response '200', 'query result export', :pdf, type: File
+
+  # method signature
+  response_ref code_compkey_hash
+  # usage
+  response_ref '700' => :RespComp, '800' => :RespComp
+  ```
+  
+  **practice:** Combined with wrong class, automatically generate error responses. TODO
   
-##### \>\> DSL methods inside apis_set'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb)# CtrlInfoObj )
+- security: TODO
+
+- server: TODO
+  
+#### \>\> DSL methods inside apis_set'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
+
+(Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
 
 These methods in the block describe the current controller, 
-or we say, these methods eventually produce reusable components.
+in other words, these methods eventually produce reusable components.
 
 So, the following methods are used as above, except that you need to 
 name the key of the component, and pass it as the first of argument list, like:
@@ -208,23 +361,74 @@ The recommended writing is:
 query! :QueryCompUuid => [:product_uuid, Integer, ...]
 ```
 The DSL methods used to generate the components in this block are: 
-(explained above)
 
-- param family methods (except `param_ref`)
-- request_body family methods (except `body_ref`)
+- param family methods (except `param_ref`) (explained above)
+- request_body family methods (except `body_ref`) (explained above)
+- schema: define Schema Object component.
+  
+  ```ruby
+  # method signature
+  schema component_key, type, schema_hash
+  # usage
+  schema :Dog  => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+  # or (unrecommended)
+  schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
+  ```
 
+### Generate JSON Documentation File
 
+Initializer or Console, run:
 
-### Generate JSON Documentation File
+```ruby
+OpenApi.write_docs
+```
 
+Then the JSON files will be written to the directory you set. (Each API a file.)
 
-### Use Swagger-UI(Very Beautiful Web UI) to show your Documentation
+### Use Swagger UI(very beautiful web page) to show your Documentation
 
+Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3) 
+to your project,  
+modify the default JSON file path(url) in the index.html 
+(window.onload >> SwaggerUIBundle >> url).  
+In order to use it, you may have to enable CORS, [see](https://github.com/swagger-api/swagger-ui#cors-support)
 
-## Troubleshooting
+### Tricks
 
+#### Write the DSL Somewhere Else (Recommend)
 
+Does your documentation take too mant lines?  
+Do you want to separate documentation from business controller to simplify both?  
+Very easy! Just use `ctrl_path`.
 
+```ruby
+# config/initializers/open_api.rb
+# in your configure
+root_controller: BaseDoc
+
+# app/api_doc/base_doc.rb
+require 'open_api/dsl'
+
+class BaseDoc < Object
+  include OpenApi::DSL
+end
+
+# app/api_doc/v1/examples_doc.rb
+class V1::ExamplesDoc < BaseDoc
+  ctrl_path 'api/v1/examples'
+  
+  open_api :index do
+    # ...
+  end
+end
+```
+
+Notes: convention is the file name ends with `_doc.rb`
+
+## Troubleshooting
+
+- **You wrote document of the current API, but not find in the generated json file?**  
+  Check your routing settings.
 
 ## Development
 
@@ -232,10 +436,6 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/zhandao/zero-rails_openapi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/README_zh.md

@@ -0,0 +1 @@
+TODO = ▽ =

data/{lib → documentation}/examples/examples_controller.rb

@@ -1,10 +1,10 @@
 class Api::V1::ExamplesController < Api::V1::BaseController
   apis_set 'ExamplesController\'s APIs' do
     schema :Dog           => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+    query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
     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 ]
+    body!  :RqBodyComp    => [ :form ]
   end
 
   open_api_set %i[index show], 'common response' do

data/{lib → documentation}/examples/open_api.rb

@@ -53,11 +53,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/api/v1',
+                        url: 'http://localhost:2333',
                         # 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',
+                        url: 'http://localhost:3332',
                         description: 'Optional server description, e.g. Internal staging server for testing'
                     }],
 

data/documentation/parameter.md

@@ -0,0 +1,55 @@
+### More Explanation of Param() 
+
+- [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 
+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.   
+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:
+  - **String, 'binary', 'base64'**
+  - **Integer, Long, 'int32', 'int64', Float, Double**
+  - **File** (it will be converted as `{ type: 'string', format: OpenApi.config.dft_file_format }`)
+  - **Date, DateTime**
+  - **Boolean**
+  - **Array**: `Array[String]` or `[String]`
+  - Nested Array: `[[[Integer]]]`
+  - **Object**: you can use just `Object`, or use a hash to declare its properties `{ id!: Integer, name: String }` 
+  (`!` bang key means it is required).
+  - Nested Object: `{ id!: Integer, name: { first: String, last: String } }`
+  - Nested Array and Object: `[[{ id!: Integer, name: { first: String, last: String } }]]`
+  - **:ComponentKey**: the Symbol value pass to type will generate a Schema Reference Object link 
+  to the component correspond to ComponentKey.
+  
+  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
+
+- 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)  
+  Must be Array or Range(will be converted to Array)
+  - value (must_be, allowable_value)  
+  Single value, could be a String, Array ...  
+  - range (number_range)  
+  Allow value in this continuous range. Set this field like this: `{ gt: 0, le: 5 }`
+  - 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)  
+    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.  
+    3. So I suggest that the value of `format` should related to data type, `is` should be an entity.  
+    4. ZRO defaults to identify whether `is` patterns matched the name, then automatically generate `is`. 
+    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)

data/lib/oas_objs/schema_obj.rb

@@ -51,7 +51,7 @@ module OpenApi
           { type: t }
         end
       end
-      def recursive_obj_type(t) # DSL use { k:v } to represent object structure
+      def recursive_obj_type(t) # DSL use { prop_name: prop_type } to represent object structure
         return processed_type(t) unless t.is_a? Hash
 
         _schema = {
@@ -59,9 +59,9 @@ module OpenApi
             properties: { },
             required: [ ]
         }
-        t.each do |k, v|
-          _schema[:required] << "#{k}".delete('!') if "#{k}".match? '!'
-          _schema[:properties]["#{k}".delete('!').to_sym] = recursive_obj_type v
+        t.each do |prop_name, prop_type|
+          _schema[:required] << "#{prop_name}".delete('!') if "#{prop_name}".match? '!'
+          _schema[:properties]["#{prop_name}".delete('!').to_sym] = recursive_obj_type prop_type
         end
         _schema.keep_if &value_present
       end
@@ -69,7 +69,8 @@ module OpenApi
         if t.is_a? Array
           {
               type: 'array',
-              items: recursive_array_type(t[0])
+              # TODO: [[String], [Integer]] <= One Of? Object?(0=>[S], 1=>[I])
+              items: recursive_array_type(t.first)
           }
         else
           processed_type t
@@ -134,17 +135,18 @@ module OpenApi
         _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 a addition
+        _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   ],
       }.each do |key, aliases|
         define_method key do
-          aliases.each do |alias_name|
-            break if self[key] == false
-            self[key] ||= self[alias_name]
-          end if self[key].nil?
-          self[key]
+          self[key].tap do |it|
+            aliases.each do |alias_name|
+              break if it == false
+              it ||= self[alias_name]
+            end if it.nil?
+          end
         end
         define_method "#{key}=" do |value| self[key] = value end
       end

data/lib/open_api/dsl.rb

@@ -8,10 +8,15 @@ module OpenApi
 
     # TODO: Doc-Block Comments
     module ClassMethods
+      def ctrl_path path
+        @_ctrl_path = path
+        @_apis_tag  = path.split('/').last.camelize
+      end
+
       def apis_set desc = '', external_doc_url = '', &block
-        @_api_infos, @_ctrl_infos = { }, { }
+        @_ctrl_infos = { }
         # current `tag`, this means that tags is currently divided by controllers.
-        tag = @_ctrl_infos[:tag] = { name: controller_name.camelize }
+        tag = @_ctrl_infos[:tag] = { name: @_apis_tag ||= controller_name.camelize }
         tag[:description]  = desc if desc.present?
         tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url.present?
 
@@ -20,38 +25,39 @@ module OpenApi
       end
 
       def open_api method, summary = '', &block
-        # select the routing info corresponding to the current method from the routing list.
-        action_path = "#{controller_path}##{method}"
+        apis_set if @_ctrl_infos.nil?
+
+        # 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
-        puts "[zero-rails_openapi] Routing mapping failed: #{controller_path}##{method}" or return if routes_info.nil?
+        puts "[zero-rails_openapi] Routing mapping failed: #{@_ctrl_path}##{method}" or return if routes_info.nil?
 
         # structural { path: { http_method:{ } } }, for Paths Object.
-        # it will be merged into :paths
-        path = @_api_infos[routes_info[:path]] ||= { }
+        path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
         current_api = path[routes_info[:http_verb]] =
-            ApiInfoObj.new(action_path).merge!( summary: summary, operationId: method, tags: [controller_name.camelize] )
+            ApiInfoObj.new(action_path).merge! summary: summary, operationId: method, tags: [@_apis_tag]
 
         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 }
+            @_apis_blocks&.[](key)&.each { |blk| it.instance_eval &blk }
           end
         end
       end
 
       # For DRY; method could be symbol array
       def open_api_set method = :all, desc = '', &block
-        @apis_blocks ||= { }
+        @_apis_blocks ||= { }
         if method.is_a? Array
-          method.each { |m| (@apis_blocks[m.to_sym] ||= [ ]) << block }
+          method.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }
         else
-          (@apis_blocks[method.to_sym] ||= [ ]) << block
+          (@_apis_blocks[method.to_sym] ||= [ ]) << block
         end
       end
 
       def ctrl_routes_list
         @routes_list ||= Generator.generate_routes_list
-        @routes_list[controller_path]
+        @routes_list[@_ctrl_path]
       end
     end
   end

data/lib/open_api/dsl_inside_block.rb

@@ -9,7 +9,7 @@ module OpenApi
     module CommonDSL
       def arrow_writing_support
         Proc.new do |args, executor|
-          if args.count == 1 && args[0].is_a?(Hash)
+          if args.count == 1 && args.first.is_a?(Hash)
             send(executor, args[0].keys.first, *args[0].values.first)
           else
             send(executor, *args)
@@ -26,12 +26,12 @@ module OpenApi
 
       %i[body body!].each do |method|
         define_method method do |*args|
-          @_method_name = method
+          @method_name = method
           _request_body_agent *args
         end
       end
 
-      # code represents `component_key` when u declare response component
+      # code represents `component_key` when declare response component
       def _response code, desc, media_type = nil, schema_hash = { }
         (self[:responses] ||= { }).merge! ResponseObj.new(code, desc, media_type, schema_hash).process
       end
@@ -45,9 +45,9 @@ module OpenApi
       end
 
       { # alias_methods mapping
-        response:         %i[resp            error_response                 ],
-        default_response: %i[dft_resp                                       ],
-        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
@@ -91,7 +91,7 @@ module OpenApi
       end
 
       def _request_body_arg_agent component_key, media_type, desc = '', schema_hash = { }
-        request_body component_key, ("#{@_method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
+        request_body component_key, ("#{@method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
       end
     end # ----------------------------------------- end of CtrlInfoObj
 
@@ -136,7 +136,7 @@ module OpenApi
       end
 
       def _request_body_agent media_type, desc = '', schema_hash = { }
-        request_body ("#{@_method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
+        request_body ("#{@method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
       end
 
       def body_ref component_key

data/lib/open_api/generator.rb

@@ -8,9 +8,10 @@ module OpenApi
 
     module ClassMethods
       def generate_docs(api_name = nil)
-        Rails.application.eager_load!
+        Dir['./app/controllers/**/*.rb'].each { |file| require file }
+        Dir['./app/**/*_doc.rb'].each { |file| require file }
         if api_name.present?
-          { api_name => generate_doc(api_name) }
+          [{ api_name => generate_doc(api_name) }]
         else
           OpenApi.apis.keys.map { |api_key| { api_key => generate_doc(api_key)} }.reduce({ }, :merge)
         end
@@ -27,17 +28,18 @@ module OpenApi
               })
 
         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[:tags] << ctrl.instance_variable_get('@_ctrl_infos')[:tag]
-          doc[:components].merge! ctrl.instance_variable_get('@_ctrl_infos')[:components]
+          doc[:tags] << ctrl_infos[:tag]
+          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? }
+        ($open_apis ||= { })[api_name] ||= HashWithIndifferentAccess.new(doc.delete_if { |_,v| v.blank? })
       end
 
       def write_docs
         docs = generate_docs
-        # puts docs
         output_path = OpenApi.config.file_output_path
         FileUtils.mkdir_p output_path
         docs.each do |api_name, doc|

data/lib/open_api/version.rb

@@ -1,3 +1,3 @@
 module OpenApi
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-22 00:00:00.000000000 Z
+date: 2017-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -69,11 +69,13 @@ files:
 - Gemfile.lock
 - LICENSE.txt
 - README.md
+- README_zh.md
 - Rakefile
 - bin/console
 - bin/setup
-- lib/examples/examples_controller.rb
-- lib/examples/open_api.rb
+- documentation/examples/examples_controller.rb
+- documentation/examples/open_api.rb
+- documentation/parameter.md
 - lib/oas_objs/helpers.rb
 - lib/oas_objs/media_type_obj.rb
 - lib/oas_objs/param_obj.rb