Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

support property example #901

Merged
merged 7 commits into from
Nov 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,9 @@ desc
required
Set this true/false to make it required/optional. Default is optional

example
Provide the example for this parameter.

allow_nil
Setting this to true means that ``nil`` can be passed.

Expand Down Expand Up @@ -349,8 +352,8 @@ Example:
.. code:: ruby

param :user, Hash, :desc => "User info" do
param :username, String, :desc => "Username for login", :required => true
param :password, String, :desc => "Password for login", :required => true
param :username, String, :desc => "Username for login", :required => true, :example => 'John'
param :password, String, :desc => "Password for login", :required => true, :example => '1234567'
param :membership, ["standard","premium"], :desc => "User membership"
param :admin_override, String, :desc => "Not shown in documentation", :show => false
param :ip_address, String, :desc => "IP address", :required => true, :missing_message => lambda { I18n.t("ip_address.required") }
Expand Down
9 changes: 9 additions & 0 deletions lib/apipie/generator/swagger/param_description/builder.rb
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ def to_swagger

definition.merge!(for_default)
definition.merge!(for_required)
definition.merge!(for_example)
definition.merge!(@description.to_hash) if @description.present?

warn_optional_without_default_value(definition)
Expand All @@ -78,6 +79,14 @@ def for_default
}
end

def for_example
return {} unless @param_description.options.key?(:example)

{
example: @param_description.options[:example],
}
end

def required?
required_from_path? || @param_description.required
end
Expand Down
2 changes: 1 addition & 1 deletion spec/dummy/app/controllers/pets_controller.rb
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ class PetsController < ApplicationController
#-----------------------------------------------------------
api :GET, "/pets/:id/as_properties", "Get a pet record"
returns :code => 200 do
property :pet_name, String, :desc => "Name of pet", :required => false
property :pet_name, String, :desc => "Name of pet", :required => false, :example => 'mypet'
property :animal_type, %w[dog cat iguana kangaroo], :desc => "Type of pet" # required by default, because this is a 'property'
end
returns :code => 404 do
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@

let(:response_description_dsl) do
proc do
property :a_number, Integer
property :an_optional_number, Integer, required: false
property :a_number, Integer, example: 1
property :an_optional_number, Integer, required: false, example: 2
end
end

Expand Down Expand Up @@ -56,10 +56,10 @@
expect(properties).to eq(
{
a_number: {
type: 'number', required: true
type: 'number', required: true, example: 1
},
an_optional_number: {
type: 'number'
type: 'number', example: 2
}
}
)
Expand All @@ -72,10 +72,10 @@
expect(properties).to eq(
{
a_number: {
type: %w[number null], required: true
type: %w[number null], required: true, example: 1
},
an_optional_number: {
type: %w[number null]
type: %w[number null], example: 2
}
}
)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -200,4 +200,16 @@
it { is_expected.to be_present }
end
end

describe 'example' do
subject { generated_block[:example] }

it { is_expected.to be_blank }

context 'when example is assigned' do
let(:base_param_description_options) { { example: 'example' } }

it { is_expected.to eq('example') }
end
end
end
4 changes: 2 additions & 2 deletions spec/lib/apipie/swagger_generator_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

let(:response_description_dsl) do
proc do
property :a_number, Integer
property :a_number, Integer, example: 1
property :an_optional_number, Integer, required: false
end
end
Expand Down Expand Up @@ -61,7 +61,7 @@
expect(properties).to eq(
{
a_number: {
type: 'number', required: true
type: 'number', required: true, example: 1
},
an_optional_number: {
type: 'number'
Expand Down
5 changes: 5 additions & 0 deletions spec/lib/swagger/rake_swagger_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ def expect_body_param_def(http_method, path, param_name, field, value)
expect(param[field]).to eq(value)
end

def expect_response_params_def(http_method, path, response_code, param_name, field, value)
param = apidoc_swagger["paths"][path][http_method]["responses"][response_code.to_s]["schema"]["properties"][param_name]
expect(param[field]).to eq(value)
end

describe 'apipie:static_swagger_json[development,json,_tmp]' do
it "generates static swagger files for the default version of apipie docs" do
Expand All @@ -105,6 +109,7 @@ def expect_body_param_def(http_method, path, param_name, field, value)
%w[finance operations sales marketing HR])

expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
expect_response_params_def("get", "/pets/{id}/as_properties", 200, "pet_name", "example", "mypet")
end

it "generates a valid swagger file" do
Expand Down
Loading