zero-rails_openapi 1.3.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b5be5f5f85b9f720f9fafaa70ba037879c336e0
-  data.tar.gz: fc93ab5059ff2ff594e080e51cb349a9a1ffd64c
+  metadata.gz: cc28a19288b67c33764363217945eabe353cbe19
+  data.tar.gz: 383973acb33b8dbbf4e0706e3854aadd252709a1
 SHA512:
-  metadata.gz: f0f37a9cb0e11cb4850819e6ed443c6f6b2386ec0f2b47878eb16b1a375e2c50fb8c6b0a2cea3446010eb3b07bc7d709f6aa74b0773d23e88962c3037222e734
-  data.tar.gz: 0db4a7fdc0f13cb55b654ff1362d39a67c399ab5f8ffa0e40eabad9c3f4776042a77c2ac189af281de0208d274d441276c10aeb7fc2b4e486753cc2f0780cae0
+  metadata.gz: c599c44d70844213307c8c00e3aac227776df6446236fde17cb021468187ac286bebfae40a82bc316ce553511972b74d72c838f0453548762628b5ed676e4581
+  data.tar.gz: 9637974d052bfa81702bd379034454a5a85fa20b2a86f2f74f0f117585f03268a5b7f52563f9ddb69e2657519ade1ba9e20c4c8595efb4a5fb0b4d24d7283e18

data/.rubocop.yml

@@ -0,0 +1,91 @@
+# This is the configuration used to check the rubocop source code.
+
+#require: rbocop/cop/internal_affairs
+
+AllCops:
+  # Include common Ruby source files.
+  Exclude:
+    - 'spec/**/*'
+    - 'zero-params_processor.gemspec'
+    - 'Gemfile'
+    - 'bin/**/*'
+  DisplayCopNames: true
+  TargetRubyVersion: 2.4
+  TargetRailsVersion: 5.1
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 1200
+
+Metrics/ClassLength:
+  Max: 1200
+
+Metrics/MethodLength:
+  Max: 1200
+
+Metrics/ModuleLength:
+  Max: 1200
+
+Metrics/BlockLength:
+  Max: 1200
+
+Style/Documentation:
+  Enabled: false
+
+Layout/SpaceInsideBrackets:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+Layout/SpaceInsidePercentLiteralDelimiters:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Layout/IndentHash:
+  Enabled: false
+
+Layout/AlignHash:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Layout/EmptyLines:
+  Enabled: false
+
+Lint/UnneededSplatExpansion:
+  Enabled: false
+
+#Style/StringLiterals:
+#  Enabled: true
+#  EnforcedStyle: double_quotes
+
+
+
+
+Style/UnneededPercentQ:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# False positives
+Layout/EmptyLineBetweenDefs:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.3.3)
+    zero-rails_openapi (1.4.0)
       activesupport (>= 3)
       rails (>= 3)
 
@@ -53,15 +53,17 @@ GEM
     erubi (1.7.0)
     globalid (0.4.1)
       activesupport (>= 4.2.0)
-    i18n (0.9.1)
+    i18n (0.9.0)
       concurrent-ruby (~> 1.0)
     loofah (2.1.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
-    mail (2.7.0)
-      mini_mime (>= 0.1.1)
+    mail (2.6.6)
+      mime-types (>= 1.16, < 4)
     method_source (0.9.0)
-    mini_mime (0.1.4)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
     mini_portile2 (2.3.0)
     minitest (5.10.3)
     nio4r (2.1.0)

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 will.huang
+Copyright (c) 2017 zhandao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -8,12 +8,9 @@
 
 ## 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 = ▽ =
+  **Hi, here is ZhanDao = ▽ =
+  I think it's a very useful tool when you want to write API document clearly.  
+  I'm looking forward to your issue and PR, thanks!**
 
 ## Table of Contents
 
@@ -21,6 +18,8 @@
 - [Installation](#installation)
 - [Configure](#configure)
 - [Usage - DSL](#usage---dsl)
+  - [DSL methods inside `open_api` and `api_dry`'s block](#dsl-methods-inside-open_api-and-api_drys-block)
+  - [DSL methods inside `components`'s block](#dsl-methods-inside-componentss-block-code-source-ctrlinfoobj-)
 - [Usage - Generate JSON documentation file](#usage---generate-json-documentation-file)
 - [Usage - Use Swagger UI(very beautiful web page) to show your Documentation](#usage---use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
 - [Tricks](#tricks)
@@ -28,8 +27,10 @@
     - [Global DRYing](#trick2---global-drying)
     - [Auto generate description](#trick3---auto-generate-description)
     - [Skip or Use parameters define in api_dry](#trick4---skip-or-use-parameters-define-in-api_dry)
-    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5---auto-generate-indexshow-actionss-responses-based-on-db-schema)
+    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
+    - [Combined Schema (oneOf / allOf / anyOf / not)]()
 - [Troubleshooting](#troubleshooting)
+- [About `OpenApi.docs` and `OpenApi.paths_index`]()
 
 ## About OAS
 
@@ -73,7 +74,7 @@
     # [REQUIRED] The output location where .json doc file will be written to.
     c.file_output_path = 'public/open_api'
   
-    c.register_docs = {
+    c.open_api_docs = {
         homepage_api: {
             # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
             root_controller: Api::V1::BaseController,
@@ -105,14 +106,15 @@
   
   OpenApi::Config.tap do |c|
     c.instance_eval do
-      api :homepage_api, root_controller: ApiDoc
+      open_api :homepage_api, root_controller: ApiDoc
       info version: '1.0.0', title: 'Homepage APIs'
     end
   end
   ```
   
-  For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)  
-  See all the settings you can configure: [config.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/config.rb)
+  For more detailed configuration: [open_api.rb](documentation/examples/open_api.rb)  
+  See all the settings you can configure: [config.rb](lib/open_api/config.rb)  
+  See all the Config DSL: [config_dsl.rb](lib/open_api/config_dsl.rb)
 
 ## Usage - DSL
 
@@ -131,17 +133,17 @@
   
   ```ruby
   class Api::V1::ExamplesController < Api::V1::BaseController
-    open_api :index, 'GET list' do
+    api :index, 'GET list' do
       query :page, Integer#, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
       query :rows, Integer#, desc: 'per page', range: { ge: 1 }, default: 10
     end
   end
   ```
   
-  For more example, see [goods_doc.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb), and
-  [examples_controller.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/examples_controller.rb)
+  For more example, see [goods_doc.rb](documentation/examples/goods_doc.rb), and
+  [examples_controller.rb](documentation/examples/examples_controller.rb)
 
-### DSL methods of controller ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl.rb))
+### DSL methods of controller ([source code](lib/open_api/dsl.rb))
 
 #### (1) `ctrl_path` (controller path) [optional]
 
@@ -182,7 +184,7 @@
   end
   
   # to use component
-  open_api :action, 'summary' do
+  api :action, 'summary' do
     query :doge, :DogSchema # to use a Schema component
     param_ref :UidQuery     # to use a Parameter component
     response_ref :BadRqResp # to use a Response component
@@ -210,29 +212,29 @@
   
   As you think, the block will be executed to each specified API(action) **firstly**.
   
-#### (5) `open_api` [required]
+#### (5) `api` [required]
 
   Define the specified API (controller action, in the following example is index).
   
   ```ruby
   # method signature
-  open_api(action, summary = '', builder: nil, skip: [ ], use: [ ], &block)
+  api(action, summary = '', builder: nil, skip: [ ], use: [ ], &block)
   # usage
-  open_api :index, '(SUMMARY) this api blah blah ...', builder: :index # block ...
+  api :index, '(SUMMARY) this api blah blah ...', builder: :index # block ...
   ```
   If you pass `builder`, and `generate_jbuilder_file` is set to `true` (in your initializer),
   ZRO will generate JBuilder file by using specified template called `index`.  
-  About template settings, see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
+  About template settings, see: [open_api.rb](documentation/examples/open_api.rb)
   
   `use` and `skip` options: to use or skip the parameters defined in `api_dry`.
   
   ```ruby
-  open_api :show, 'summary', use: [:id] # => it will only take :id from DRYed result.
+  api :show, 'summary', use: [:id] # => it will only take :id from DRYed result.
   ```
 
-### DSL methods inside [open_api]() and [api_dry]()'s block
+### DSL methods inside [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
+  [source code](lib/open_api/dsl/api_info_obj.rb)
   
   These following methods in the block describe the specified API action: description, valid?,
   parameters, request body, responses, securities, servers.
@@ -304,15 +306,26 @@
   param_ref :IdPath, :NameQuery, :TokenHeader
   
   
-  # method signature
-   header(param_name, schema_type, schema_hash = { })
-  header!(param_name, schema_type, schema_hash = { })
-   query!(param_name, schema_type, schema_hash = { })
-  # usage
+  ### method signature
+   header(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
+  header!(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
+   query!(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
+  # ...
+  ### usage
   header! 'Token', String
   query!  :readed, Boolean, must_be: true, default: false
   # The same effect as above, but not simple
-  param   :query, :readed, Boolean, :req, must_be: true, default: false
+  param :query, :readed, Boolean, :req, must_be: true, default: false
+  #
+  # When schema_type is a Object 
+  #   (describe by hash, key means prop's name, value means prop's schema_type)
+  query :good, { name: String, price: Float, spec: { size: String, weight: Integer } }, desc: 'good info'
+  # Or you can use `type:` to sign the schema_type, maybe this is clearer for describing object
+  query :good, type: { name: String, price: Float, spec: { size: String, weight: Integer } }, desc: 'good info'
+  #
+  query :good_name, type: String # It's also OK, but some superfluous
+  query :good_name, String       # recommended
+  # About Combined Schema (`one_of` ..), see the link below.
 
 
   # method signature
@@ -340,8 +353,10 @@
           :wrong_input => [ -1, ''   ]
   }
   ```
+  
+  [This trick show you how to define combined schema (by using `one_of` ..)]()
 
-  [**>> More About `param` DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
+  [**>> More About `param` DSL <<**](documentation/parameter.md)
 
 #### (4) `request_body` family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
 
@@ -408,7 +423,7 @@
   1. **Notice:** Each API should only declare a request body
      That is, all of the above methods you can only choose one of them.  
      (But **multiple media types** will be supported in the future).
-  2. `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.  
+  2. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
   3. `schema_hash`: as above (see param).  
      **One thing that should be noted is: when use Hash writing, `scham_type` is writed in schema_hash using key :type.**
   4. `exp_by` and `examples`: for the above example, the following has the same effect:
@@ -427,6 +442,7 @@
   response_ref
   default_response or dft_resp
   error_response, other_response, oth_resp, error, err_resp # response's aliases, should be used in the error response context.
+  merge_to_resp
   ```
   
   ```ruby
@@ -439,15 +455,87 @@
   response_ref(code_compkey_hash)
   # usage
   response_ref 700 => :AResp, 800 => :BResp
+
+  # method signature
+  merge_to_resp(code, by:)
+  # usage
+  merge_to_resp 200, by: {
+      data: {
+          type: String
+      }
+  }
+  ```
+  
+  **practice:** Combined with wrong class, automatically generate error responses. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)  
+  
+#### (6) Authentication and Authorization
+  
+  First of all, please make sure that you have read one of the following documents:  
+  [OpenApi Auth](https://swagger.io/docs/specification/authentication/) 
+  or [securitySchemeObject](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject)
+  
+  ##### Define Security Scheme
+  
+  Use these DSL in your initializer or `components` block:
   ```
+  security_scheme # alias `auth_scheme`
+  base_auth       # will call `security_scheme`
+  bearer_auth     # will call `security_scheme`
+  api_key         # will call `security_scheme`
+  ```
+  It's very simple to use (if you understand the above document)
+  ```ruby
+  # method signature
+  security_scheme(scheme_name, other_info)
+  # usage
+  security_scheme :BasicAuth, { type: 'http', scheme: 'basic', desc: 'basic auth' }
   
-  **practice:** Combined with wrong class, automatically generate error responses. [AutoGenDoc](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L63)  
+  # method signature
+  base_auth(scheme_name, other_info = { })
+  bearer_auth(scheme_name, format = 'JWT', other_info = { })
+  api_key(scheme_name, field:, in:, **other_info)
+  # usage
+  base_auth :BasicAuth, desc: 'basic auth' # the same effect as ↑↑↑
+  bearer_auth :Token
+  api_key :ApiKeyAuth, field: 'X-API-Key', in: 'header', desc: 'pass api key to header'
+  ```
+  
+  ##### Apply Security
   
-#### (6) `security`: TODO
+  ```
+  # In initializer
+  # Global effectiveness
+  global_security_require
+  global_security # alias
+  global_auth     # alias
+  
+  # In `api`'s block
+  # Only valid for the current controller
+  security_require
+  security  # alias
+  auth      # alias
+  need_auth # alias
+  ```
+  Name is different, signature and usage is similar.
+  ```ruby
+  # method signature
+  security_require(scheme_name, scopes: [ ])
+  # usage
+  global_auth :Token
+  need_auth   :Token
+  auth :OAuth, scopes: %w[ read_example admin ]
+  ```
 
-#### (7) `server`: TODO
+#### (7) Overriding Global Servers by `server`
   
-### DSL methods inside [components]()'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
+  ```ruby
+  # method signature
+  server(url, desc)
+  # usage
+  server 'http://localhost:3000', 'local'
+  ```
+  
+### DSL methods inside [components]()'s block ([code source](lib/open_api/dsl/ctrl_info_obj.rb):: CtrlInfoObj )
 
   (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
   
@@ -469,18 +557,20 @@
   # method signature
   schema(component_key, type, schema_hash)
   # usage
-  schema :Dog  => [ String, desc: 'dogee' ]
+  schema :Dog  => [ String, desc: 'dogee' ] # <= schema_type is `String`
   # advance usage
-  schema :Dog => [{
-                       id!: Integer,
-                       name: { type: String, must_be: 'name', desc: 'name' }
-                   }, # <= this hash is schema type[1]
-                   dft: { id: 1, name: 'pet' },
-                   desc: 'dogee']
+  schema :Dog => [
+      {
+          id!: Integer,
+          name: { type: String, must_be: 'name', desc: 'name' }
+      }, # <= this hash is schema type[1]
+      dft: { id: 1, name: 'pet' },
+      desc: 'dogee'
+  ]
   # or (unrecommended)
   schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }, desc: 'dogee'
   ```
-  [1] see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
+  [1] see: [Type](documentation/parameter.md#type-schema_type)
 
 ## Usage - Generate JSON Documentation File
 
@@ -491,7 +581,7 @@
   OpenApi.write_docs generate_files: !Rails.env.production?
   
   # or run directly in console
-  OpenApi.write_docs
+  OpenApi.write_docs # will generate json doc files
   ```
   
   Then the JSON files will be written to the directories you set. (Each API a file.)
@@ -500,8 +590,7 @@
 
   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).  
+  change the default JSON file path(url) in index.html.  
   In order to use it, you may have to enable CORS, [see](https://github.com/swagger-api/swagger-ui#cors-support)
 
 ## Tricks
@@ -528,7 +617,7 @@
   class V1::ExamplesDoc < ApiDoc
     ctrl_path 'api/v1/examples'
     
-    open_api :index do
+    api :index do
       # ...
     end
   end
@@ -540,7 +629,7 @@
 
   Method `api_dry` is for DRY but its scope is limited to the current controller.
   
-  I have no idea of best practices, But you can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb).  
+  I have no idea of best practices, But you can look at this [file](documentation/examples/auto_gen_doc.rb).  
   The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
   
   You can use `sort` to specify the order of parameters.
@@ -572,30 +661,68 @@
                  'only offline': :offline,
               'expensive goods': :get,
                   'cheap goods': :borrow,
-      }
+  }
   ```
-  Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_desc.rb) to learn more.
+  Read this [file](documentation/examples/auto_gen_desc.rb) to learn more.
 
 ### Trick4 - Skip or Use parameters define in api_dry
 
-  Pass `skip: []` and `use: []` to `open_api` like following code:
+  Pass `skip: []` and `use: []` to `api` like following code:
   ```ruby
-  open_api :index, 'desc', builder: :index, skip: [ :Token ]
+  api :index, 'desc', builder: :index, skip: [ :Token ]
   ```
   
-  Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb) to learn more.
+  Look at this [file](documentation/examples/goods_doc.rb) to learn more.
 
 ### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
 
   Use method `load_schema` in `api_dry`.
   
-  See this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L51) for uasge information.
+  See this [file](documentation/examples/auto_gen_doc.rb#L51) for uasge information.
+
+### Trick6 - Combined Schema (oneOf / allOf / anyOf / not)
 
+  ```ruby
+  query :combination, one_of: [ :GoodSchema, String, { type: Integer, desc: 'integer input'}]
+  
+  form '', data: {
+      :combination_in_form => { any_of: [ Integer, String ] }
+  }
+  
+  schema :PetSchema => [ not: [ Integer, Boolean ] ]
+  ```
+  
+  OAS: [link1](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/),
+  [link2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject)
 
 ## Troubleshooting
 
 - **You wrote document of the current API, but not find in the generated json file?**  
   Check your routing settings.
+- **Undefine method `match?`**  
+  Monkey patches for `String` and `Symbol`:  
+  ```ruby
+  class String # Symbol
+    def match?(pattern); !match(pattern).nil? end
+  end
+  ```
+- **Report error when require `routes.rb`?***
+  1. Run `rails routes`.
+  2. Copy the output to a file, for example `config/routes.txt`.  
+     ignore the file `config/routes.txt`.
+  3. Put `c.rails_routes_file = 'config/routes.txt'` to your ZRO config.
+
+
+## About `OpenApi.docs` and `OpenApi.paths_index`
+
+  After `OpenApi.write_docs`, the above two module variables will be generated.
+  
+  `OpenApi.docs`: A Hash with API names as keys, and documents of each APIs as values.  
+  documents are instances of ActiveSupport::HashWithIndifferentAccess.
+  
+  `OpenApi.paths_index`: Inverted index of controller path to API name mappings.  
+  Like: `{ 'api/v1/examples' => :homepage_api }`  
+  It's useful when you want to look up a document based on a controller and do something.
 
 ## Development
 
@@ -609,4 +736,4 @@
 
 ## Code of Conduct
 
-  Everyone interacting in the Zero-OpenApi project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zhandao/zero-rails_openapi/blob/master/CODE_OF_CONDUCT.md).
+  Everyone interacting in the Zero-OpenApi project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).