diff --git a/CHANGELOG.md b/CHANGELOG.md index f776bf878..ef2b8ee1e 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 `summary`, `hidden`, `deprecated`, `is_array`, `nickname`, `produces`, `consumes`, `tags` options in `desc` block - [@darren987469](https://github.com/darren987469). #### Fixes diff --git a/README.md b/README.md index e3ed789f7..94e80896d 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 ['application/json'] + consumes ['application/json'] + 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..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. @@ -78,13 +86,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..bd9f61c5f 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: %w[array of mime_types], + consumes: %w[array of mime_types], + tags: %w[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 %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)