zero-rails_openapi 1.3.2 → 1.3.3

data/documentation/examples/examples_controller.rb

@@ -23,9 +23,9 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     desc 'Optional multiline or single-line Markdown-formatted description',
          id:         'user id',
          email_addr: 'email_addr\'s desc'
-    email = 'git@github.com'
+    email = 'zero@rails.org'
 
-    query! :id,         Integer, enum: 0..5,     length: [1, 2], pattern: /^[0-9]$/, range: {gt:0, le:5}
+    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
 

data/documentation/examples/goods_doc.rb

@@ -1,12 +1,13 @@
 class V2::GoodsDoc < BaseDoc
 
-  open_api :index, 'Get list of Goods.', builder: :index,
-           use: [ 'Token' ] do # use parameters write in AutoGenDoc#api_dry
-           # skip: %i[ Token ] do # you can also skip parameters
+  open_api :index, 'GET list of Goods.', builder: :index, # jbuilder templates is set in initializers/open_api.rb
+           use: [ 'Token', :page, :rows ] do # use parameters write in AutoGenDoc#api_dry
+           # skip: [ 'Token' ] do # you can also skip parameters
     desc 'listing Goods',
          view!: 'search view, allows:：<br/>',
          search_type!: 'search field, allows：<br/>'
 
+    # Single `query`
     query :view, String, enum: {
         'all goods (default)': :all,
                 'only online': :online,
@@ -14,22 +15,23 @@ class V2::GoodsDoc < BaseDoc
             'expensive goods': :expensive,
                 'cheap goods': :cheap,
     }
-    # query :search_type, String, enum: %w[name creator category price]
+    # Batch `query`
     do_query by: {
         :search_type => { type: String, enum: %w[ name creator category price ] },
-        :export => { type: Boolean, desc: 'export as Excel format', examples: {
-            :right_input => true,
-            :wrong_input => 'wrong input'
-        }}
+              :value => String,
+             :export => { type: Boolean, desc: 'export as Excel format', examples: {
+                 :right_input => true,
+                 :wrong_input => 'wrong input'
+             }}
     }
   end
 
 
-  open_api :create, 'Create a Good', builder: :success_or_not, use: 'Token' do
+  open_api :create, 'POST create a Good', builder: :success_or_not, use: 'Token' do
     form! 'for creating a good', data: {
                :name! => { type: String,  desc: 'good\'s name' },
         :category_id! => { type: Integer, desc: 'sub_category\'s id', npmt: true, range: { ge: 1 }, as: :cate  },
-              :price! => { type: Float,   desc: 'good\'s price', range: { ge: 0} },
+              :price! => { type: Float,   desc: 'good\'s price', range: { ge: 0 } },
         # -- optional
            :is_online => { type: Boolean, desc: 'it\'s online?' },
              :remarks => { type: String,  desc: 'remarks' },
@@ -43,8 +45,8 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  open_api :show, 'Show a Good.', builder: :show, use: [ 'Token', :id ]
+  open_api :show, 'GET a Good.', builder: :show, use: [ 'Token', :id ]
 
 
-  open_api :destroy, 'Delete a Good.', builder: :success_or_not, use: [ 'Token', :id ]
+  open_api :destroy, 'DELETE a Good.', builder: :success_or_not, use: [ 'Token', :id ]
 end

data/documentation/examples/open_api.rb

@@ -1,6 +1,16 @@
 require 'open_api'
 
 OpenApi::Config.tap do |c|
+  # Config DSL
+  c.instance_eval do
+    api :zero_rails_api, root_controller: ApiDoc
+    info version: '0.0.1', title: 'Zero Rails APIs', description: 'API documentation of Zero-Rails Application.'
+    server 'http://localhost:3000', desc: 'Main (production) server'
+    server 'http://localhost:3000', desc: 'Internal staging server for testing'
+    security ApiKeyAuth: [ ]
+    security_scheme :ApiKeyAuth, type: 'apiKey', name: 'server_token', in: 'query'
+  end
+
   # [REQUIRED] The location where .json doc file will be output.
   c.file_output_path = 'public/open_api'
 
@@ -88,7 +98,7 @@ OpenApi::Config.tap do |c|
   c.jbuilder_templates = {
       index: (
       <<~FILE
-        # *** Generated by ZRO ***
+        # *** Generated by ZRO [ please make sure that you have checked this file ] ***
         json.partial! 'api/base', total: @data.size
         
         json.data do
@@ -103,7 +113,7 @@ OpenApi::Config.tap do |c|
 
       show: (
       <<~FILE
-        # *** Generated by ZRO ***
+        # *** Generated by ZRO [ please make sure that you have checked this file ] ***
         json.partial! 'api/base', total: 1
         
         json.data do
@@ -116,14 +126,14 @@ OpenApi::Config.tap do |c|
 
       success: (
       <<~FILE
-        # *** Generated by ZRO ***
+        # *** Generated by ZRO [ please make sure that you have checked this file ] ***
         json.partial! 'api/success'
       FILE
       ),
 
       success_or_not: (
       <<~FILE
-        # *** Generated by ZRO ***
+        # *** Generated by ZRO [ please make sure that you have checked this file ] ***
         unless @status
           # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
         end

data/documentation/parameter.md

@@ -1,21 +1,26 @@
-### More Explanation of Param() 
+### More Explanation for `param` and `schema_hash`
 
-#### param_type
+#### param_type (param_location)
 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`.
+#### name (param_name)
+The name of parameter. It can be Symbol or String.
+
+If param_type is :path, it must correspond to the associated path segment form 
+the routing path, for example: if the API path is `/good/:id`, you have to declare a path parameter with name `id` to it.
+
+#### type (schema_type)
+Parameter's (schema) type. We call it `schema_type` because it is inside SchemaObj.
+
+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:
+All the types you can use as following:
   - **String, 'binary', 'base64'**
   - **Integer, Long, 'int32', 'int64', Float, Double**
-  - **File** (it will be converted as `{ type: 'string', format: Config.dft_file_format }`)
+  - **File** (it will be converted to `{ type: 'string', format: Config.dft_file_format }`)
   - **Date, DateTime**
   - **Boolean**
   - **Array**: `Array[String]` or `[String]`
@@ -24,8 +29,8 @@ All the types you can use are:
   (`!` 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.
+  - **:ComponentKey**: pass **Symbol** value to type will generate a Schema Reference Object link 
+  to the component correspond to ComponentKey, like: :IdPath, :NameQuery
   
   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.
@@ -59,4 +64,4 @@ You can set the schema by following keys (all are optional), the words in parent
     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)**
-  - **as** # TODO
+  - **as** # TODO

data/lib/oas_objs/schema_obj.rb

@@ -33,7 +33,7 @@ module OpenApi
                processed_is_and_format(param_name),
                {
                    pattern:    _pattern&.inspect&.delete('/'),
-                   default:    '_default',
+                   default:    _default.nil? ? nil : '_default',
                    examples:   self[:examples].present? ? ExampleObj.new(self[:examples], self[:exp_by]).process : nil,
                },
                { as: _as, permit: _permit, not_permit: _npermit, req_if: _req_if, opt_if: _opt_if }

data/lib/open_api/config.rb

@@ -18,20 +18,20 @@ module OpenApi
     # Getting started: https://swagger.io/docs/specification/basic-structure/
     cattr_accessor :register_docs do
       {
-          # [REQUIRED] At least one doc.
-          zero_rails: {
-              # [REQUIRED] ZRO will scan all the descendants of the root_controller, and then generate their docs.
-              root_controller: ApplicationController,
-
-              # [REQUIRED] Info Object: The info section contains API information
-              info: {
-                  # [REQUIRED] The title of the application.
-                  title: 'Zero Rails Apis',
-                  # [REQUIRED] The version of the OpenAPI document
-                  # (which is distinct from the OpenAPI Specification version or the API implementation version).
-                  version: '0.0.1'
-              }
-          }
+      #     # [REQUIRED] At least one doc.
+      #     zero_rails_api: {
+      #         # [REQUIRED] ZRO will scan all the descendants of the root_controller, and then generate their docs.
+      #         root_controller: ApplicationController,
+      #
+      #         # [REQUIRED] Info Object: The info section contains API information
+      #         info: {
+      #             # [REQUIRED] The title of the application.
+      #             title: 'Zero Rails Apis',
+      #             # [REQUIRED] The version of the OpenAPI document
+      #             # (which is distinct from the OpenAPI Specification version or the API implementation version).
+      #             version: '0.0.1'
+      #         }
+      #     }
       }
     end
 
@@ -55,7 +55,7 @@ module OpenApi
       {
           index: (
           <<~FILE
-            # *** Generated by ZRO ***
+            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
             json.partial! 'api/base', total: @data.size
             
             json.data do
@@ -70,7 +70,7 @@ module OpenApi
 
           show: (
           <<~FILE
-            # *** Generated by ZRO ***
+            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
             json.partial! 'api/base', total: 1
             
             json.data do
@@ -83,14 +83,14 @@ module OpenApi
 
           success: (
           <<~FILE
-            # *** Generated by ZRO ***
+            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
             json.partial! 'api/success'
           FILE
           ),
 
           success_or_not: (
           <<~FILE
-            # *** Generated by ZRO ***
+            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
             unless @status
               # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
             end

data/lib/open_api/config_dsl.rb

@@ -4,8 +4,27 @@ module OpenApi
       base.class_eval do
         module_function
 
-        def info
-          1
+        def api name, root_controller:
+          @api = name
+          register_docs[name] = { root_controller: root_controller }
+        end
+
+        def info version:, title:, **addition
+          register_docs[@api].merge! version: version, title: title, **addition
+        end
+
+        def server url, desc: ''
+          (register_docs[@api][:servers] ||= [ ]) << { url: url, description: desc }
+        end
+
+        def security requirement
+          (register_docs[@api][:global_security] ||= [ ]) << requirement
+        end
+
+        alias_method :security_require, :security
+
+        def security_scheme scheme_name, schema# = { }
+          (register_docs[@api][:global_security_schemes] ||= { }).merge! scheme_name => schema
         end
       end
     end

data/lib/open_api/dsl.rb

@@ -26,28 +26,28 @@ module OpenApi
       def components &block
         apis_tag if @_ctrl_infos.nil?
         current_ctrl = @_ctrl_infos[:components] = CtrlInfoObj.new
-        current_ctrl.instance_eval &block
+        current_ctrl.instance_eval(&block)
         current_ctrl._process_objs
       end
 
-      def open_api method, summary = '', builder: nil, skip: [ ], use: [ ], &block
+      def open_api action, summary = '', builder: nil, skip: [ ], use: [ ], &block
         apis_tag if @_ctrl_infos.nil?
 
-        # select the routing info (corresponding to the current method) from the routing list.
-        action_path = "#{@_ctrl_path ||= controller_path}##{method}"
+        # select the routing info (corresponding to the current method) from routing list.
+        action_path = "#{@_ctrl_path ||= controller_path}##{action}"
         routes_info = ctrl_routes_list&.select { |api| api[:action_path].match? /^#{action_path}$/ }&.first
-        pp "[ZRO Warning] Routing mapping failed: #{@_ctrl_path}##{method}" and return if routes_info.nil?
+        pp "[ZRO Warning] Routing mapping failed: #{@_ctrl_path}##{action}" and return if routes_info.nil?
         Generator.generate_builder_file(action_path, builder) if builder.present?
 
         # structural { #path: { #http_method:{ } } }, for pushing into Paths Object.
         path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
         current_api = path[routes_info[:http_verb]] =
             ApiInfoObj.new(action_path, skip: Array(skip), use: Array(use))
-                .merge! description: '', summary: summary, operationId: method, tags: [@_apis_tag],
+                .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
                         parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
 
         current_api.tap do |api|
-          [method, :all].each do |key| # blocks_store_key
+          [action, :all].each do |key| # blocks_store_key
             @_apis_blocks&.[](key)&.each { |blk| api.instance_eval(&blk) }
           end
           api.param_use = [ ] # skip 和 use 是对 dry 块而言的
@@ -58,18 +58,17 @@ module OpenApi
       end
 
       # method could be symbol array, like: %i[ .. ]
-      def api_dry method = :all, desc = '', &block
+      def api_dry action = :all, desc = '', &block
         @_apis_blocks ||= { }
-        if method.is_a? Array
-          method.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }
+        if action.is_a? Array
+          action.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }
         else
-          (@_apis_blocks[method.to_sym] ||= [ ]) << block
+          (@_apis_blocks[action.to_sym] ||= [ ]) << block
         end
       end
 
       def ctrl_routes_list
-        @routes_list ||= Generator.generate_routes_list
-        @routes_list[@_ctrl_path]
+        Generator.routes_list[@_ctrl_path]
       end
     end
   end

data/lib/open_api/dsl/api_info_obj.rb

@@ -6,7 +6,7 @@ module OpenApi
       include DSL::CommonDSL
       include DSL::Helpers
 
-      attr_accessor :action_path, :param_skip, :param_use, :param_descs
+      attr_accessor :action_path, :param_skip, :param_use, :param_descs, :param_order
 
       def initialize(action_path, skip: [ ], use: [ ])
         self.action_path = action_path
@@ -50,7 +50,7 @@ module OpenApi
       %i[header header! path path! query query! cookie cookie!].each do |param_type|
         define_method "do_#{param_type}" do |by:|
           by.each do |key, value|
-            args = [ key.dup.to_s.delete('!'), value.delete(:type), value ]
+            args = [ key.dup.to_s.delete('!').to_sym, value.delete(:type), value ]
             key.to_s['!'] ? send("#{param_type}!", *args) : send(param_type, *args)
           end
         end unless param_type.to_s['!']
@@ -113,12 +113,37 @@ module OpenApi
         self[:servers] << { url: url, description: desc }
       end
 
+      def order *param_names
+        self.param_order = param_names
+      end
+
+      def param_examples exp_by = :all, examples_hash
+        _process_objs
+        exp_by = self[:parameters].map { |p| p[:name] } if exp_by == :all
+        # TODO: ref obj
+        # exp_in_params = self[:parameters].map { |p| p[:schema][:examples] }.compact
+        # examples_hash.map! do |key, value|
+        #   if value == []
+        #     if key.in?(exp_in_params.map { |e| e.keys }.flatten.uniq)
+        #       # TODO
+        #     end
+        #   end
+        # end
+        self[:examples] = ExampleObj.new(examples_hash, exp_by).process
+      end
+      alias_method :examples, :param_examples
+
 
       def _process_objs
         self[:parameters]&.each_with_index do |p, index|
           self[:parameters][index] = p.process if p.is_a?(ParamObj)
         end
 
+        # Parameters sorting
+        self[:parameters].clone.each do |p|
+          self[:parameters][param_order.index(p[:name])] = p
+        end if param_order.present?
+
         self[:responses]&.each do |code, obj|
           self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
         end

data/lib/open_api/dsl/common_dsl.rb

@@ -3,6 +3,7 @@ require 'oas_objs/param_obj'
 require 'oas_objs/response_obj'
 require 'oas_objs/request_body_obj'
 require 'oas_objs/ref_obj'
+require 'oas_objs/example_obj'
 require 'open_api/dsl/helpers'
 
 module OpenApi

data/lib/open_api/dsl/ctrl_info_obj.rb

@@ -6,7 +6,7 @@ module OpenApi
       include DSL::CommonDSL
       include DSL::Helpers
 
-      def schema component_key, type, schema_hash = { }
+      def schema component_key, type, schema_hash# = { }
         (self[:schemas] ||= { })[component_key] = SchemaObj.new(type, schema_hash).process
       end
       arrow_enable :schema

data/lib/open_api/dsl/helpers.rb

@@ -11,9 +11,9 @@ module OpenApi
         #   (2) config in model: https://github.com/zhandao/zero-rails/tree/master/app/models/good.rb
         #   (3) jbuilder file: https://github.com/zhandao/zero-rails/blob/mster/app/views/api/v1/goods/index.json.jbuilder
         # in a word, BuilderSupport let you control the `output fields and nested association infos` very easily.
-        if model&.respond_to? :show_attrs
+        if model.respond_to? :show_attrs
           columns = model.columns.map(&:name).map(&:to_sym)
-          model&.show_attrs&.map do |attr|
+          model.show_attrs.map do |attr|
             if columns.include? attr
               index = columns.index attr
               type = model.columns[index].sql_type_metadata.type.to_s.camelize
@@ -26,13 +26,13 @@ module OpenApi
             end rescue next
           end
         else
-          model&.columns&.map do |column|
+          model.columns.map do |column|
             name = column.name.to_sym
             type = column.sql_type_metadata.type.to_s.camelize
             type = 'DateTime' if type == 'Datetime'
             { name => Object.const_get(type) }
           end
-        end&.compact&.reduce({ }, :merge)
+        end.compact.reduce({ }, :merge) rescue ''
       end
 
       # Arrow Writing: