zero-rails_openapi 1.2.0 → 1.3.0

data/documentation/examples/examples_controller.rb

@@ -16,7 +16,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     response '567', 'query result export', :pdf, type: File
   end
 
-  open_api :index, '(SUMMARY) this api blah blah ...' do
+  open_api :index, '(SUMMARY) this api blah blah ...', builder: :template1 do
     this_api_is_invalid! 'this api is expired!'
     desc 'Optional multiline or single-line Markdown-formatted description',
          id:         'user id',

data/documentation/examples/goods_doc.rb

@@ -0,0 +1,38 @@
+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
+    desc 'listing Goods',
+         view!: 'search view, allows:：<br/>',
+         search_type!: 'search field, allows：<br/>'
+
+    query :view, String, enum: {
+        'all goods (default)': :all,
+                'only online': :online,
+               'only offline': :offline,
+            'expensive goods': :expensive,
+                'cheap goods': :cheap,
+    }
+    query :search_type, String, enum: %w[name creator category price]
+  end
+
+
+  open_api :create, '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} },
+        # -- optional
+           :is_online => { type: Boolean, desc: 'it\'s online?' },
+             :remarks => { type: String,  desc: 'remarks' },
+            :pic_path => { type: String,  desc: 'picture url', is: :url },
+    }
+  end
+
+
+  open_api :show, 'Show a Good.', builder: :show, 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,6 @@
 require 'open_api'
 
-OpenApi.configure do |c|
+OpenApi::Config.tap do |c|
   # [REQUIRED] The location where .json doc file will be output.
   c.file_output_path = 'public/open_api'
 
@@ -82,6 +82,54 @@ OpenApi.configure do |c|
           global_security: [{ ApiKeyAuth: [] }],
       }
   }
+
+  c.generate_jbuilder_file  = true
+  c.overwrite_jbuilder_file = false
+  c.jbuilder_templates = {
+      index: (
+      <<-FILE
+json.partial! 'api/base', total: @data.count
+
+json.data do
+  # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
+  # json.array! @data do |datum|
+  json.array! @data.page(@_page).per(@_rows) do |datum|
+    json.(datum, *datum.show_attrs) if datum.present?
+  end
+end
+      FILE
+      ),
+
+      show: (
+      <<-FILE
+json.partial! 'api/base', total: 1
+
+json.data do
+  json.array! [ @data ] do |datum|
+    json.(datum, *datum.show_attrs) if datum.present?
+  end
+end
+      FILE
+      ),
+
+      success: (
+      <<-FILE
+json.partial! 'api/success'
+      FILE
+      ),
+
+      success_or_not: (
+      <<-FILE
+unless @status
+  # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
+end
+
+json.partial! 'api/base', total: 0
+json.data ''
+      FILE
+      ),
+  }
+
 end
 
 Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL

data/documentation/parameter.md

@@ -15,7 +15,7 @@ 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 }`)
+  - **File** (it will be converted as `{ type: 'string', format: Config.dft_file_format }`)
   - **Date, DateTime**
   - **Boolean**
   - **Array**: `Array[String]` or `[String]`
@@ -58,4 +58,5 @@ You can set the schema by following keys (all are optional), the words in parent
     [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)**
+  - **default (dft, default_value)**
+  - **as** # TODO

data/lib/oas_objs/helpers.rb

@@ -10,11 +10,13 @@ module OpenApi
       proc { |_, v| truly_present? v }
     end
 
+    # assign.to
     def assign(value)
       @assign = value.is_a?(Symbol) ? send("_#{value}") : value
       self
     end
 
+    # reduceee.then_merge! => for Hash
     def reduceee(*values)
       @assign = values.compact.reduce({ }, :merge).keep_if &value_present
       self

data/lib/oas_objs/media_type_obj.rb

@@ -7,7 +7,7 @@ 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[:data], schema_hash)
+        self.schema     = SchemaObj.new(schema_hash.values_at(:type, :data, :t).compact.first, schema_hash)
       end
 
       def process

data/lib/oas_objs/schema_obj.rb

@@ -30,12 +30,15 @@ module OpenApi
                  processed_range,
                  processed_is_and_format(param_name),
                  {
-                     pattern: _pattern&.inspect&.delete('/'),
-                     default: _default,
+                     pattern:    _pattern&.inspect&.delete('/'),
+                     default:    _default,
+                     as:         _as,
+                     permit:     _permit,
+                     not_permit: _npermit,
                  }
         then_merge!
 
-        assign(processed_desc options).then_merge!
+        reduceee(processed_desc options).then_merge!
       end
       alias_method :process, :process_for
 
@@ -51,15 +54,17 @@ module OpenApi
         options[:desc_inside] ? { description: result } : nil
       end
 
+      # TODO: more info
+      # TODO: desc configure
       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/>"
+              __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
             end
           else
             processed[:enum].each_with_index do |value, index|
-              __desc.concat "#{index + 1}/ #{value}<br/>"
+              __desc.concat "<br/>#{index + 1}/ #{value}"
             end
           end
         end
@@ -69,7 +74,7 @@ module OpenApi
       def processed_type(type = self.type)
         t = type.class.in?([Hash, Array, Symbol]) ? type : "#{type}".downcase
         if t.is_a? Hash
-          # For support writing:
+          # For supporting writing:
           #   form 'desc', data: {
           #     id!: { type: Integer, enum: 0..5, desc: 'user id' }
           # }
@@ -87,7 +92,7 @@ module OpenApi
         elsif t.in? %w[binary base64]
           { type: 'string', format: t}
         elsif t.eql? 'file'
-          { type: 'string', format: OpenApi.config.dft_file_format }
+          { type: 'string', format: Config.dft_file_format }
         elsif t.eql? 'datetime'
           { type: 'string', format: 'date-time' }
         else # other string
@@ -177,7 +182,7 @@ module OpenApi
       end
       def recognize_is_options_in(name)
         # identify whether `is` patterns matched the name, if so, generate `is`.
-        OpenApi.config.is_options.each do |pattern|
+        Config.is_options.each do |pattern|
           self._is = pattern or break if name.match? /#{pattern}/
         end if _is.nil?
         self.delete :_is if _is.in?([:x, :we])
@@ -188,13 +193,16 @@ module OpenApi
           _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
+          _length:  %i[ length   lth     size             ],
+          _is:      %i[ is_a     is                       ], # NOT OAS Spec, see documentation/parameter.md
           _format:  %i[ format   fmt                      ],
-          _pattern: %i[ pattern  regexp  pr   reg         ],
+          _pattern: %i[ pattern  regexp  pt   reg         ],
           _default: %i[ default  dft     default_value    ],
-          _desc:    %i[ desc     description              ],
-          __desc:   %i[ desc!    description!             ],
+          _desc:    %i[ desc     description  d           ],
+          __desc:   %i[ desc!    description! d!          ],
+          _as:      %i[ as   to  for     map  mapping     ], # NOT OAS Spec, it's for zero-params_processor
+          _permit:  %i[ permit   pmt                      ], # NOT OAS Spec, it's for zero-params_processor
+          _npermit: %i[ npmt     not_permit   unpermit    ], # NOT OAS Spec, it's for zero-params_processor
       }.each do |key, aliases|
         define_method key do
           aliases.each do |alias_name|

data/lib/open_api.rb

@@ -4,6 +4,5 @@ require "open_api/generator"
 require "open_api/dsl"
 
 module OpenApi
-  include Config
   include Generator
 end

data/lib/open_api/config.rb

@@ -1,34 +1,100 @@
 module OpenApi
   module Config
-    def self.included(base)
-      base.extend ClassMethods
-    end
-
-    DEFAULT_CONFIG = {
-        is_options: %w[email phone password uuid uri url time date],
-        dft_file_format: 'binary'
-    }.freeze
-
-    module ClassMethods
-      def config
-        @config ||= ActiveSupport::InheritableOptions.new(DEFAULT_CONFIG)
-      end
-
-      def configure(&block)
-        config.instance_eval &block
-      end
-
-      ### config options
-      # register_docs = {
-      #     doc_name: {
-      #         :file_output_path, :root_controller
-      #         info: {}
-      #     }}
-      # is_options = %w[]
-
-      def apis
-        @apis ||= @config.register_docs
-      end
+    # [REQUIRED] The location where .json doc file will be output.
+    cattr_accessor :file_output_path do
+      'public/open_api'
+    end
+
+    cattr_accessor :generate_doc do
+      true
+    end
+
+    # 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/
+    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'
+              }
+          }
+      }
+    end
+
+    cattr_accessor :is_options do
+      %w[ email phone password uuid uri url time date ]
+    end
+
+    cattr_accessor :dft_file_format do
+      'binary'
+    end
+
+    cattr_accessor :generate_jbuilder_file do
+      false
+    end
+
+    cattr_accessor :overwrite_jbuilder_file do
+      false
+    end
+
+    cattr_accessor :jbuilder_templates do
+      {
+          index: (
+          <<-FILE
+json.partial! 'api/base', total: @data.count
+
+json.data do
+  # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
+  # json.array! @data do |datum|
+  json.array! @data.page(@_page).per(@_rows) do |datum|
+    json.(datum, *datum.show_attrs) if datum.present?
+  end
+end
+          FILE
+          ),
+
+          show: (
+          <<-FILE
+json.partial! 'api/base', total: 1
+
+json.data do
+  json.array! [ @data ] do |datum|
+    json.(datum, *datum.show_attrs) if datum.present?
+  end
+end
+          FILE
+          ),
+
+          success: (
+          <<-FILE
+json.partial! 'api/success'
+          FILE
+          ),
+
+          success_or_not: (
+          <<-FILE
+unless @status
+  # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
+end
+
+json.partial! 'api/base', total: 0
+json.data ''
+          FILE
+          ),
+      }
+    end
+
+    def self.docs
+      register_docs
     end
   end
 end

data/lib/open_api/dsl.rb

@@ -24,33 +24,40 @@ module OpenApi
         current_ctrl.instance_eval &block if block_given?
       end
 
-      def open_api method, summary = '', &block
+      def open_api method, summary = '', options = { }, &block
         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: #{@_ctrl_path}##{method}" or return if routes_info.nil?
+        pp "[ZRO Warnning] Routing mapping failed: #{@_ctrl_path}##{method}" and return if routes_info.nil?
 
-        # structural { path: { http_method:{ } } }, for Paths Object.
+        # 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)
+            ApiInfoObj.new(action_path, options.slice(:skip, :use))
                 .merge! description: '', summary: summary, operationId: method, tags: [@_apis_tag],
-                        parameters: [ ], requestBody: '', responses: { },
-                        security: [ ], servers: [ ]
+                        parameters: [ ], requestBody: '', responses: { }, security: [ ], servers: [ ]
 
-        current_api.tap do |it|
+        if (builder = options.values_at(:builder, :bd, :jbuilder).compact.first).present?
+          Generator
+              .generate_builder_file path:    action_path.split('#').first,
+                                     action:  action_path.split('#').last,
+                                     builder: builder
+        end
+
+        current_api.tap do |api|
           [method, :all].each do |key| # blocks_store_key
-            @_apis_blocks&.[](key)&.each { |blk| it.instance_eval &blk }
+            @_apis_blocks&.[](key)&.each { |blk| api.instance_eval &blk }
           end
-          it.instance_eval &block if block_given?
-          it.instance_eval { process_params }
-          it.delete_if { |_, v| v.blank? }
+          api.param_use = nil
+          api.instance_eval &block if block_given?
+          api.instance_eval { process_params }
+          api.delete_if { |_, v| v.blank? }
         end
       end
 
-      # For DRY; method could be symbol array
+      # method could be symbol array, like: %i[ .. ]
       def api_dry method = :all, desc = '', &block
         @_apis_blocks ||= { }
         if method.is_a? Array

data/lib/open_api/dsl_inside_block.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 'open_api/helpers'
 
 module OpenApi
   module DSL
@@ -100,10 +101,13 @@ module OpenApi
 
     class ApiInfoObj < Hash
       include DSL::CommonDSL
+      include DSL::Helpers
 
-      attr_accessor :action_path
-      def initialize(action_path)
+      attr_accessor :action_path, :param_skip, :param_use
+      def initialize(action_path, options = { })
         self.action_path = action_path
+        self.param_skip  = options[:skip] || [ ]
+        self.param_use   = options[:use]  || [ ]
       end
 
       def this_api_is_invalid! explain = ''
@@ -131,6 +135,9 @@ module OpenApi
       end
 
       def param param_type, name, type, required, schema_hash = { }
+        return if param_skip.include? name
+        return unless param_use.include? name if param_use.present?
+
         if @inputs_descs&.[](name).present?
           schema_hash[:desc] = @inputs_descs[name]
         elsif @inputs_descs&.[]("#{name}!".to_sym).present?
@@ -139,7 +146,9 @@ module OpenApi
 
         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
+        index = self[:parameters].map do |p|
+          p.processed[:name] if p.is_a? ParamObj
+        end.index name
         if index.present?
           self[:parameters][index] = param_obj
         else
@@ -148,8 +157,8 @@ module OpenApi
       end
 
       def process_params
-        self[:parameters].each_with_index do |param_obj, index|
-          self[:parameters][index] = param_obj.process
+        self[:parameters].each_with_index do |p, index|
+          self[:parameters][index] = p.is_a?(ParamObj) ? p.process : p
         end
       end