From 89c4d2c24605797d07e7f9e2bf81d17bcf9b3bcb Mon Sep 17 00:00:00 2001 From: darren987469 Date: Sat, 15 Sep 2018 22:19:43 +0800 Subject: [PATCH 1/3] Support more options in desc blockFix #1789.Support `summary`, `hidden`, `deprecated`, `is_array`, `nickname`,`produces`, `consumes`, `tags` options in desc block. --- CHANGELOG.md | 1 + README.md | 16 ++++++++++++++-- lib/grape/dsl/desc.rb | 10 +++++++++- spec/grape/dsl/desc_spec.rb | 18 +++++++++++++++++- 4 files changed, 41 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f776bf878..2618feff2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ #### Features * Your contribution here. +* [#1791](https://github.com/ruby-grape/grape/pull/1791): Support more options in desc block - [@darren987469](https://github.com/darren987469). #### Fixes diff --git a/README.md b/README.md index e3ed789f7..22026dd7a 100644 --- a/README.md +++ b/README.md @@ -446,10 +446,13 @@ version 'v1', using: :param, parameter: 'v' ## Describing Methods -You can add a description to API methods and namespaces. +You can add a description to API methods and namespaces. The description would be used by [grape-swagger][grape-swagger] to generate swagger compliant documentation. + +Note: Description block is only for documentation and won't affects API behavior. ```ruby desc 'Returns your public timeline.' do + summary 'summary' detail 'more details' params API::Entities::Status.documentation success API::Entities::Entity @@ -463,7 +466,13 @@ desc 'Returns your public timeline.' do description: 'Not really needed', required: false } - + hidden false + deprecated false + is_array true + nickname 'nickname' + produces ['array', 'of', 'mime_types'] + consumes ['array', 'of', 'mime_types'] + tags ['tag1', 'tag2'] end get :public_timeline do Status.limit(20) @@ -476,6 +485,9 @@ end * `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities * `named`: A helper to give a route a name and find it with this name in the documentation Hash * `headers`: A definition of the used Headers +* Other options can be found in [grape-swagger][grape-swagger] + +[grape-swagger]: https://github.com/ruby-grape/grape-swagger ## Parameters diff --git a/lib/grape/dsl/desc.rb b/lib/grape/dsl/desc.rb index e758bf2c9..7e088d4d6 100644 --- a/lib/grape/dsl/desc.rb +++ b/lib/grape/dsl/desc.rb @@ -78,13 +78,21 @@ def unset_description_field(field) def desc_container Module.new do include Grape::Util::StrictHashConfiguration.module( + :summary, :description, :detail, :params, :entity, :http_codes, :named, - :headers + :headers, + :hidden, + :deprecated, + :is_array, + :nickname, + :produces, + :consumes, + :tags ) def config_context.success(*args) diff --git a/spec/grape/dsl/desc_spec.rb b/spec/grape/dsl/desc_spec.rb index a7ff7da33..496122f01 100644 --- a/spec/grape/dsl/desc_spec.rb +++ b/spec/grape/dsl/desc_spec.rb @@ -21,6 +21,7 @@ class Dummy it 'can be set with a block' do expected_options = { + summary: 'summary', description: 'The description', detail: 'more details', params: { first: :param }, @@ -34,10 +35,18 @@ class Dummy XOptionalHeader: { description: 'Not really needed', required: false - }] + }], + hidden: false, + deprecated: false, + is_array: true, + nickname: 'nickname', + produces: ['array', 'of', 'mime_types'], + consumes: ['array', 'of', 'mime_types'], + tags: ['tag1', 'tag2'] } subject.desc 'The description' do + summary 'summary' detail 'more details' params(first: :param) success Object @@ -51,6 +60,13 @@ class Dummy description: 'Not really needed', required: false }] + hidden false + deprecated false + is_array true + nickname 'nickname' + produces ['array', 'of', 'mime_types'] + consumes ['array', 'of', 'mime_types'] + tags ['tag1', 'tag2'] end expect(subject.namespace_setting(:description)).to eq(expected_options) From ab6670117f954928bf680cdab8ba99e81089e16a Mon Sep 17 00:00:00 2001 From: darren987469 Date: Sun, 16 Sep 2018 10:31:12 +0800 Subject: [PATCH 2/3] Fix rubocop and update CHANGELOG --- CHANGELOG.md | 2 +- spec/grape/dsl/desc_spec.rb | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2618feff2..ef2b8ee1e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ #### Features * Your contribution here. -* [#1791](https://github.com/ruby-grape/grape/pull/1791): Support more options in desc block - [@darren987469](https://github.com/darren987469). +* [#1791](https://github.com/ruby-grape/grape/pull/1791): Support `summary`, `hidden`, `deprecated`, `is_array`, `nickname`, `produces`, `consumes`, `tags` options in `desc` block - [@darren987469](https://github.com/darren987469). #### Fixes diff --git a/spec/grape/dsl/desc_spec.rb b/spec/grape/dsl/desc_spec.rb index 496122f01..bd9f61c5f 100644 --- a/spec/grape/dsl/desc_spec.rb +++ b/spec/grape/dsl/desc_spec.rb @@ -40,9 +40,9 @@ class Dummy deprecated: false, is_array: true, nickname: 'nickname', - produces: ['array', 'of', 'mime_types'], - consumes: ['array', 'of', 'mime_types'], - tags: ['tag1', 'tag2'] + produces: %w[array of mime_types], + consumes: %w[array of mime_types], + tags: %w[tag1 tag2] } subject.desc 'The description' do @@ -64,9 +64,9 @@ class Dummy deprecated false is_array true nickname 'nickname' - produces ['array', 'of', 'mime_types'] - consumes ['array', 'of', 'mime_types'] - tags ['tag1', 'tag2'] + produces %w[array of mime_types] + consumes %w[array of mime_types] + tags %w[tag1 tag2] end expect(subject.namespace_setting(:description)).to eq(expected_options) From 8204bdb44bfa5ca0ee5b3bd0bd1722466a4e2f1f Mon Sep 17 00:00:00 2001 From: darren987469 Date: Sun, 16 Sep 2018 18:08:16 +0800 Subject: [PATCH 3/3] Refine documentation [ci skip] Add real mime type in README. Add options documentation in `desc`. --- README.md | 4 ++-- lib/grape/dsl/desc.rb | 8 ++++++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 22026dd7a..94e80896d 100644 --- a/README.md +++ b/README.md @@ -470,8 +470,8 @@ desc 'Returns your public timeline.' do deprecated false is_array true nickname 'nickname' - produces ['array', 'of', 'mime_types'] - consumes ['array', 'of', 'mime_types'] + produces ['application/json'] + consumes ['application/json'] tags ['tag1', 'tag2'] end get :public_timeline do diff --git a/lib/grape/dsl/desc.rb b/lib/grape/dsl/desc.rb index 7e088d4d6..1fe128127 100644 --- a/lib/grape/dsl/desc.rb +++ b/lib/grape/dsl/desc.rb @@ -4,6 +4,7 @@ module Desc include Grape::DSL::Settings # Add a description to the next namespace or function. + # @option options :summary [String] summary for this endpoint # @param description [String] descriptive string for this endpoint # or namespace # @param options [Hash] other properties you can set to describe the @@ -17,6 +18,13 @@ module Desc # endpoint may return, with their meanings, in a 2d array # @option options :named [String] a specific name to help find this route # @option options :headers [Hash] HTTP headers this method can accept + # @option options :hidden [Boolean] hide the endpoint or not + # @option options :deprecated [Boolean] deprecate the endpoint or not + # @option options :is_array [Boolean] response entity is array or not + # @option options :nickname [String] nickname of the endpoint + # @option options :produces [Array[String]] a list of MIME types the endpoint produce + # @option options :consumes [Array[String]] a list of MIME types the endpoint consume + # @option options :tags [Array[String]] a list of tags # @yield a block yielding an instance context with methods mapping to # each of the above, except that :entity is also aliased as #success # and :http_codes is aliased as #failure.