zero-rails_openapi 1.5.4 → 1.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a1ad9dd33921ca9718211e6c4b3a4952e7c9462
-  data.tar.gz: 5983dbcfc189d115bcd79b6b0495b77f450af71e
+  metadata.gz: e530c334773b9ef483102a2cd2c829704ac41ab4
+  data.tar.gz: 2cabf4dc3335eeea103fbca8863c01ba46b9988a
 SHA512:
-  metadata.gz: 4d0b87971da06837b09304c04d8319bced499990d3634f8146cee33e87ee914c34995a648bc2b019606a8502c38759c593194e334a5745ea72be14c3b4f1c498
-  data.tar.gz: 39055363665e740d3a88d2672622fbc5f5d80949dc1973b7d3346b4a52522a6e1ab86136d1584c517f0229af27a83b6784013a7dd9b63037a69f027870891183
+  metadata.gz: 1bee517abfc870ee6cac040f9a61cc03e724e9e240fdc3aa2b4a7ce217f99ed57724d00d00b00741a1694e75cba9e4368f554cdddddad6c6d407a607a3daba96
+  data.tar.gz: 73da6d4109dc89c1e079e83dac675099f203c83b00dad28e6da023a1cb1f97344feb0bb283d25e6f0a5ceff25c033cc2d703cac2f3d95240f986d329e420b9a5

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [1.5.5] - 2018/2/21 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.5.4...v1.5.5)
+
+## Added
+
+1. Callback Object has been supported. (issue [#12](#https://github.com/zhandao/zero-rails_openapi/issues/12) @austbot)
+
+## Changed
+
+1. `mk`'s parameter `eq` is changed to `get`. (dssl.rb)
+
 ## [1.5.4] - 2018/2/15 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.5.3...v1.5.4)
 
 Thanks to @austbot, fix - colorize fails at runtime.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.5.4)
+    zero-rails_openapi (1.5.5)
       activesupport (>= 3)
       colorize (= 0.8.1)
       rails (>= 3)

data/README.md

@@ -4,8 +4,6 @@
   [![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
   [![Maintainability](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/maintainability)](https://codeclimate.com/github/zhandao/zero-rails_openapi/maintainability)
   [![Test Coverage](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/test_coverage)](https://codeclimate.com/github/zhandao/zero-rails_openapi/test_coverage)
-  [![Gitter Chat](https://badges.gitter.im/zero-rails_openapi/Lobby.svg)](https://gitter.im/zero-rails_openapi/Lobby)
-  [![Help Contribute to Open Source](https://www.codetriage.com/zhandao/zero-rails_openapi/badges/users.svg)](https://www.codetriage.com/zhandao/zero-rails_openapi)
 
   Concise DSL for generating OpenAPI Specification 3 (**OAS3**, formerly Swagger3) JSON documentation for Rails application.
 
@@ -25,7 +23,20 @@
 - [Configure](#configure)
 - [Usage - DSL](#usage---dsl)
   - [Basic DSL](#basic-dsl)
+    - [route_base](#1-route_base-optional-if-youre-writing-dsl-in-controller)
+    - [doc_tag](#2-doc_tag-optional)
+    - [components](#3-components-optional)
+    - [api_dry](#4-api_dry-optional)
+    - [api](#5-api-required)
   - [DSL methods inside `api` and `api_dry`'s block](#dsl-methods-inside-api-and-api_drys-block)
+    - [this_api_is_invalid!](#1-this_api_is_invalid-its-aliases)
+    - [desc](#2-desc-description-for-the-current-api-and-its-inputs-parameters-and-request-body)
+    - [param family methods](#3-param-family-methods-oas---parameter-object)
+    - [request_body family methods](#4-request_body-family-methods-oas---request-body-object)
+    - [response family methods](#5-response-family-methods-oas---response-object)
+    - [callback](#6-callback-oas---callback-object)
+    - [Authentication and Authorization](#7-authentication-and-authorization)
+    - [server](#8-overriding-global-servers-by-server)
   - [DSL methods inside `components`'s block](#dsl-methods-inside-componentss-block-code-source)
 - [Run! - Generate JSON documentation file](#run---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)
@@ -45,7 +56,7 @@
 
   You can getting started from [swagger.io](https://swagger.io/docs/specification/basic-structure/)
 
-  **I suggest you should understand OAS3's basic structure at least.**
+  **I suggest you should understand the basic structure of OAS3 at least.**
   such as component (can help you reuse DSL code, when your apis are used with the
   same data structure).
 
@@ -150,7 +161,8 @@
   ```
 
   For more example, see [goods_doc.rb](documentation/examples/goods_doc.rb), and
-  [examples_controller.rb](documentation/examples/examples_controller.rb)
+  [examples_controller.rb](documentation/examples/examples_controller.rb),
+  or [HERE](https://github.com/zhandao/zero-rails/tree/master/app/_docs/v1).
 
 ### Basic DSL ([source code](lib/open_api/dsl.rb))
 
@@ -492,8 +504,47 @@
   ```
 
   **practice:** Automatically generate responses based on the agreed error class. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)
+  
+### (6) Callback (OAS - [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#callback-object))
+
+  [About Callbacks](https://swagger.io/docs/specification/callbacks/)
+  > In OpenAPI 3 specs, you can define callbacks – asynchronous, out-of-band requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients.  
+    A typical example of a callback is a subscription functionality ... you can define the format of the “subscription” operation as well as the format of callback messages and expected responses to these messages.  
+    This description will simplify communication between different servers and will help you standardize use of webhooks in your API.  
+  [Complete YAML Example](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/callback-example.yaml)
+  
+  The structure of Callback Object:
+  ```
+  callbacks:
+    Event1:
+      path1:
+        ...
+      path2:
+       ...
+    Event2:
+      ...
+  ```
+  
+  To define callbacks, you can use `callback` method:
+  ```ruby
+  # method signature
+  callback(event_name, http_method, callback_url, &block)
+  # usage
+  callback :myEvent, :post, 'localhost:3000/api/goods' do
+    query :name, String
+    data :token, String
+    response 200, 'success', :json, data: { name: String, description: String }
+  end
+  ```
+  
+  Use runtime expressions in callback_url:
+  ```ruby
+  callback :myEvent, :post, '{body callback_addr}/api/goods/{query id}'
+  # the final URL will be: {$request.body#/callback_addr}/api/goods/{$request.query.id}
+  # Note: Other expressions outside "$request" are not supported yet
+  ```
 
-#### (6) Authentication and Authorization
+#### (7) 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/)
@@ -551,7 +602,7 @@
   auth :OAuth, scopes: %w[ read_example admin ]
   ```
 
-#### (7) Overriding Global Servers by `server`
+#### (8) Overriding Global Servers by `server`
 
   ```ruby
   # method signature
@@ -763,6 +814,8 @@
 
 ## Development
 
+  TODO ..
+
   After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
   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).

data/README_zh.md

@@ -28,17 +28,30 @@
 - [配置](#configure)
 - [DSL 介绍及用例](#usage---dsl)
   - [基本的 DSL](#基本的-dsl)
+    - [route_base](#1-route_base-optional-if-youre-writing-dsl-in-controller)
+    - [doc_tag](#2-doc_tag-optional)
+    - [components](#3-components-optional)
+    - [api_dry](#4-api_dry-optional)
+    - [api](#5-api-required)
   - [用于 `api` 和 `api_dry` 块内的 DSL（描述 API 的参数、响应等）](#dsl-methods-inside-api-and-api_drys-block)
+    - [this_api_is_invalid!](#1-this_api_is_invalid-its-aliases)
+    - [desc](#2-desc-description-for-the-current-api-and-its-inputs-parameters-and-request-body)
+    - [param family methods](#3-param-family-methods-oas---parameter-object)
+    - [request_body family methods](#4-request_body-family-methods-oas---request-body-object)
+    - [response family methods](#5-response-family-methods-oas---response-object)
+    - [callback](#6-callback-oas---callback-object)
+    - [Authentication and Authorization](#7-authentication-and-authorization)
+    - [server](#8-overriding-global-servers-by-server)
   - [用于 `components` 块内的 DSL（描述可复用的组件）](#dsl-methods-inside-componentss-block-code-source)
 - [执行文档生成](#run---generate-json-documentation-file)
 - [使用 Swagger-UI 可视化所生成的文档](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
 - [技巧](#tricks)
-    - [将 DSL 写于他处，与控制器分离](#trick1---write-the-dsl-somewhere-else)
-    - [全局 DRY](#trick2---global-drying)
-    - [基于 enum 等信息自动生成参数描述](#trick3---auto-generate-description)
-    - [跳过或使用 DRY 时（`api_dry`）所定义的参数](#trick4---skip-or-use-parameters-define-in-api_dry)
-    - [基于 DB Schema 自动生成 response 的格式](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
-    - [定义组合的 Schema (one_of / all_of / any_of / not)](#trick6---combined-schema-one_of--all_of--any_of--not)
+  - [将 DSL 写于他处，与控制器分离](#trick1---write-the-dsl-somewhere-else)
+  - [全局 DRY](#trick2---global-drying)
+  - [基于 enum 等信息自动生成参数描述](#trick3---auto-generate-description)
+  - [跳过或使用 DRY 时（`api_dry`）所定义的参数](#trick4---skip-or-use-parameters-define-in-api_dry)
+  - [基于 DB Schema 自动生成 response 的格式](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
+  - [定义组合的 Schema (one_of / all_of / any_of / not)](#trick6---combined-schema-one_of--all_of--any_of--not)
 - [问题集](#troubleshooting)
 - [有关 `OpenApi.docs` 和 `OpenApi.routes_index`](#about-openapidocs-and-openapiroutes_index)
 
@@ -145,8 +158,9 @@
   end
   ```
   
-  这有两份更详细的实例： [goods_doc.rb](documentation/examples/goods_doc.rb), 以及
-  [examples_controller.rb](documentation/examples/examples_controller.rb)。
+  更多更详细的实例： [goods_doc.rb](documentation/examples/goods_doc.rb)、
+  [examples_controller.rb](documentation/examples/examples_controller.rb)，以及
+  [这里](https://github.com/zhandao/zero-rails/tree/master/app/_docs/v1)。
 
 ### 基本的 DSL ([source code](lib/open_api/dsl.rb))
 

data/lib/oas_objs/callback_obj.rb

@@ -0,0 +1,58 @@
+require 'oas_objs/helpers'
+
+module OpenApi
+  module DSL
+    # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callbackObject
+    class CallbackObj < Hash
+      include Helpers
+
+      attr_accessor :event_name, :http_method, :callback_url, :block
+
+      def initialize(event_name, http_method, callback_url, &block)
+        self.event_name = event_name
+        self.http_method = http_method
+        self.callback_url = callback_url
+        self.block = block
+      end
+
+      def process
+        {
+            self.event_name => {
+                processed_url => {
+                    self.http_method.downcase.to_sym => processed_block
+                }
+            }
+        }
+      end
+
+      def processed_url
+        self.callback_url.gsub(/{[^{}]*}/) do |exp|
+          key_location, key_name = exp[1..-2].split
+          connector = key_location == 'body' ? '#/' : '.'
+          key_location = '$request.' + key_location
+          ['{', key_location, connector, key_name, '}'].join
+        end
+      end
+
+      def processed_block
+        api = ApiInfo.new.merge! parameters: [ ], requestBody: '',  responses: { }
+        api.instance_exec(&(self.block || ->{ }))
+        api.process_objs
+        api.delete_if { |_, v| v.blank? }
+      end
+    end
+  end
+end
+
+
+__END__
+
+myEvent:
+  '{$request.body#/callbackUrl}':
+    post: # Method
+      requestBody: # Contents of the callback message
+        …
+      responses: # Expected responses
+        …
+
+https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/callback-example.yaml

data/lib/oas_objs/schema_obj.rb

@@ -41,7 +41,7 @@ module OpenApi
           RefObj.new(:schema, t).process
         elsif t.in? %w[ float double int32 int64 ]
           { type: t.match?('int') ? 'integer' : 'number', format: t }
-        elsif t.in? %w[ binary base64 ]
+        elsif t.in? %w[ binary base64 uri ]
           { type: 'string', format: t }
         elsif t == 'file'
           { type: 'string', format: Config.file_format }

data/lib/open_api/dsl.rb

@@ -40,7 +40,8 @@ module OpenApi
 
         api = ApiInfo.new(action_path, skip: Array(skip), use: Array(use))
                      .merge! description: '', summary: summary, operationId: action, tags: [@doc_tag],
-                             parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+                             parameters: [ ], requestBody: '',  responses: { },  callbacks: { },
+                             links: { }, security: [ ], servers: [ ]
         [action, :all].each { |blk_key| @zro_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
         api.param_use = api.param_skip = [ ] # `skip` and `use` only affect `api_dry`'s blocks
         api.instance_exec(&block) if block_given?

data/lib/open_api/dsl/api_info.rb

@@ -8,7 +8,7 @@ module OpenApi
 
       attr_accessor :action_path, :param_skip, :param_use, :param_descs, :param_order
 
-      def initialize(action_path, skip: [ ], use: [ ])
+      def initialize(action_path = '', skip: [ ], use: [ ])
         self.action_path = action_path
         self.param_skip  = skip
         self.param_use   = use
@@ -115,6 +115,10 @@ module OpenApi
       alias auth      security_require
       alias need_auth security_require
 
+      def callback event_name, http_method, callback_url, &block
+        self[:callbacks].deep_merge! CallbackObj.new(event_name, http_method, callback_url, &block).process
+      end
+
       def server url, desc: ''
         self[:servers] << { url: url, description: desc }
       end

data/lib/open_api/dsl/common_dsl.rb

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

data/lib/open_api/version.rb

@@ -1,3 +1,3 @@
 module OpenApi
-  VERSION = '1.5.4'
+  VERSION = '1.5.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.5.4
+  version: 1.5.5
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-15 00:00:00.000000000 Z
+date: 2018-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,6 +137,7 @@ files:
 - documentation/examples/open_api.rb
 - documentation/examples/output_example.json
 - documentation/parameter.md
+- lib/oas_objs/callback_obj.rb
 - lib/oas_objs/combined_schema.rb
 - lib/oas_objs/example_obj.rb
 - lib/oas_objs/helpers.rb