diff --git a/README.rst b/README.rst index a794e87c..4a97754f 100644 --- a/README.rst +++ b/README.rst @@ -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. @@ -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") } diff --git a/lib/apipie/generator/swagger/param_description/builder.rb b/lib/apipie/generator/swagger/param_description/builder.rb index 43d81c68..eb695b1f 100644 --- a/lib/apipie/generator/swagger/param_description/builder.rb +++ b/lib/apipie/generator/swagger/param_description/builder.rb @@ -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) @@ -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 diff --git a/spec/dummy/app/controllers/pets_controller.rb b/spec/dummy/app/controllers/pets_controller.rb index 78e1f284..7935215c 100644 --- a/spec/dummy/app/controllers/pets_controller.rb +++ b/spec/dummy/app/controllers/pets_controller.rb @@ -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 diff --git a/spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb b/spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb index d6c86174..6371028a 100644 --- a/spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb +++ b/spec/lib/apipie/generator/swagger/method_description/response_schema_service_spec.rb @@ -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 @@ -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 } } ) @@ -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 } } ) diff --git a/spec/lib/apipie/generator/swagger/param_description/builder_spec.rb b/spec/lib/apipie/generator/swagger/param_description/builder_spec.rb index 7d5da214..09175fbd 100644 --- a/spec/lib/apipie/generator/swagger/param_description/builder_spec.rb +++ b/spec/lib/apipie/generator/swagger/param_description/builder_spec.rb @@ -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 diff --git a/spec/lib/apipie/swagger_generator_spec.rb b/spec/lib/apipie/swagger_generator_spec.rb index f0adb9b9..8ed6d5bf 100644 --- a/spec/lib/apipie/swagger_generator_spec.rb +++ b/spec/lib/apipie/swagger_generator_spec.rb @@ -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 @@ -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' diff --git a/spec/lib/swagger/rake_swagger_spec.rb b/spec/lib/swagger/rake_swagger_spec.rb index e6aa4284..42606544 100644 --- a/spec/lib/swagger/rake_swagger_spec.rb +++ b/spec/lib/swagger/rake_swagger_spec.rb @@ -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 @@ -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