Skip to content

Commit

Permalink
Improve API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dwilkie
dwilkie committed Jan 8, 2025
1 parent 2403dd5 commit aed3d42
Show file tree
Hide file tree
Showing 2 changed files with 154 additions and 45 deletions.
57 changes: 54 additions & 3 deletions spec/requests/open_ews_api/v1/beneficiaries/addresses_spec.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,48 @@
end

post "/v1/beneficiaries/:beneficiary_id/addresses" do
with_options scope: %i[data] do
parameter(
:type, "Must be `address`",
required: true
)
end

with_options scope: %i[data attributes] do
parameter(
:iso_country_code, "The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the address",
required: true
)
parameter(
:iso_region_code, "The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code of the address",
required: true
)
parameter(
:administrative_division_level_2_code, "The second-level administrative subdivision code of the address (e.g. district code)",
required: false
)
parameter(
:administrative_division_level_2_name, "The second-level administrative subdivision name of the address (e.g. district name)",
required: false
)
parameter(
:administrative_division_level_3_code, "The third-level administrative subdivision code of the address (e.g. commune code)",
required: false
)
parameter(
:administrative_division_level_3_name, "The third-level administrative subdivision name of the address (e.g. commune name)",
required: false
)
parameter(
:administrative_division_level_4_code, "The forth-level administrative subdivision code of the address (e.g. village code)",
required: false
)
parameter(
:administrative_division_level_4_name, "The forth-level administrative subdivision name of the address (e.g. village name)",
required: false
)
end

example "Create an address for a beneficiary" do
account = create(:account)
beneficiary = create(:beneficiary, account:)
Expand All @@ -35,17 +77,26 @@
attributes: {
iso_country_code: "KH",
iso_region_code: "KH-1",
administrative_division_level_2_code: "01"
administrative_division_level_2_code: "0102",
administrative_division_level_2_name: "Mongkol Borei",
administrative_division_level_3_code: "010201",
administrative_division_level_3_name: "Banteay Neang",
administrative_division_level_4_code: "01020101",
administrative_division_level_4_name: "Ou Thum"
}
}
)

expect(response_status).to eq(201)
expect(response_body).to match_jsonapi_resource_schema("address")
expect(jsonapi_response_attributes).to include(
"iso_country_code" => "KH",
"iso_region_code" => "KH-1",
"administrative_division_level_2_code" => "01"
"administrative_division_level_2_code" => "0102",
"administrative_division_level_2_name" => "Mongkol Borei",
"administrative_division_level_3_code" => "010201",
"administrative_division_level_3_name" => "Banteay Neang",
"administrative_division_level_4_code" => "01020101",
"administrative_division_level_4_name" => "Ou Thum"
)
end
end
Expand Down
142 changes: 100 additions & 42 deletions spec/requests/open_ews_api/v1/beneficiaries_spec.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
_other_account_beneficiary = create(:beneficiary)

set_authorization_header_for(account)
do_request
do_request(filter: { status: "active" })

expect(response_status).to eq(200)
expect(response_body).to match_jsonapi_resource_collection_schema("beneficiary")
Expand All @@ -42,13 +42,23 @@
end

post "/v1/beneficiaries" do
with_options scope: %i[data] do
parameter(
:type, "Must be `beneficiary`",
required: true
)
end
with_options scope: %i[data attributes] do
parameter(
:phone_number, "Phone number in E.164 format or shortcode.",
:phone_number, "Phone number in E.164 format.",
required: true
)
parameter(
:language_code, "Language code in ISO 639-1 format.",
:iso_country_code, "The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the beneficiary.",
required: true
)
parameter(
:language_code, "The [ISO ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) alpha-3 language code of the beneficiary.",
required: false
)
parameter(
Expand All @@ -60,43 +70,43 @@
required: false
)
parameter(
:iso_country_code, "The ISO 3166-1 alpha-2 country code of the phone number. It must be matched with the country of `phone_number` parameter.",
:metadata, "Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.",
required: false
)
end
with_options scope: %i[data attributes address] do
parameter(
:iso_country_code, "The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the address",
required: true
)
parameter(
:iso_region_code, "The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code of the address",
required: true
)
parameter(
:administrative_division_level_2_code, "The second-level administrative subdivision code of the address (e.g. district code)",
required: false
)
parameter(
:administrative_division_level_2_name, "The second-level administrative subdivision name of the address (e.g. district name)",
required: false
)
parameter(
:administrative_division_level_3_code, "The third-level administrative subdivision code of the address (e.g. commune code)",
required: false
)
parameter(
:metadata, "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.",
:administrative_division_level_3_name, "The third-level administrative subdivision name of the address (e.g. commune name)",
required: false
)
parameter(
:administrative_division_level_4_code, "The forth-level administrative subdivision code of the address (e.g. village code)",
required: false
)
parameter(
:administrative_division_level_4_name, "The forth-level administrative subdivision name of the address (e.g. village name)",
required: false
)
with_options scope: :address do
parameter(
:iso_region_code, "ISO 3166-2 of the country's subdivisions(e.g., provinces or states)",
required: false
)
parameter(
:administrative_division_level_2_code, "Code of administrative division level 2(e.g. district)",
required: false
)
parameter(
:administrative_division_level_2_name, "Name of administrative division level 2",
required: false
)
parameter(
:administrative_division_level_3_code, "Code of administrative division level 2(e.g. commune)",
required: false
)
parameter(
:administrative_division_level_3_name, "Name of administrative division level 3",
required: false
)
parameter(
:administrative_division_level_4_code, "Code of administrative division level 4(e.g. village)",
required: false
)
parameter(
:administrative_division_level_4_name, "Name of administrative division level 4",
required: false
)
end
end

example "Create a beneficiary" do
Expand All @@ -108,15 +118,20 @@
type: :beneficiary,
attributes: {
phone_number: "+85510999999",
language_code: "km",
language_code: "khm",
gender: "M",
date_of_birth: "1990-01-01",
metadata: { "foo" => "bar" },
iso_country_code: "KH",
address: {
iso_country_code: "KH",
iso_region_code: "KH-1",
administrative_division_level_2_code: "01"
administrative_division_level_2_code: "0102",
administrative_division_level_2_name: "Mongkol Borei",
administrative_division_level_3_code: "010201",
administrative_division_level_3_name: "Banteay Neang",
administrative_division_level_4_code: "01020101",
administrative_division_level_4_name: "Ou Thum"
}
}
}
Expand All @@ -126,7 +141,7 @@
expect(response_body).to match_jsonapi_resource_schema("beneficiary")
expect(jsonapi_response_attributes).to include(
"phone_number" => "+85510999999",
"language_code" => "km",
"language_code" => "khm",
"gender" => "M",
"date_of_birth" => "1990-01-01",
"metadata" => { "foo" => "bar" },
Expand All @@ -136,7 +151,12 @@
expect(json_response.dig("included", 0).to_json).to match_api_response_schema("address")
expect(json_response.dig("included", 0, "attributes")).to include(
"iso_region_code" => "KH-1",
"administrative_division_level_2_code" => "01"
"administrative_division_level_2_code" => "0102",
"administrative_division_level_2_name" => "Mongkol Borei",
"administrative_division_level_3_code" => "010201",
"administrative_division_level_3_name" => "Banteay Neang",
"administrative_division_level_4_code" => "01020101",
"administrative_division_level_4_name" => "Ou Thum"
)
end

Expand All @@ -150,7 +170,7 @@
type: :beneficiary,
attributes: {
phone_number: "+85510999999",
iso_country_code: "kh"
iso_country_code: "KH"
}
}
)
Expand Down Expand Up @@ -178,6 +198,44 @@
end

patch "/v1/beneficiaries/:id" do
with_options scope: %i[data] do
parameter(
:id, "The unique identifier of the beneficiary.",
required: true
)
parameter(
:type, "Must be `beneficiary`",
required: true
)
end

with_options scope: %i[data attributes] do
parameter(
:phone_number, "Phone number in E.164 format.",
required: true
)
parameter(
:iso_country_code, "The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the beneficiary.",
required: true
)
parameter(
:language_code, "The [ISO ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) alpha-3 language code of the beneficiary.",
required: false
)
parameter(
:gender, "Must be one of `M` or `F`.",
required: false
)
parameter(
:date_of_birth, "Date of birth in `YYYY-MM-DD` format.",
required: false
)
parameter(
:metadata, "Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.",
required: false
)
end

example "Update a beneficiary" do
beneficiary = create(
:beneficiary,
Expand All @@ -198,7 +256,7 @@
phone_number: "+85510999002",
gender: "F",
status: "disabled",
language_code: "en",
language_code: "eng",
date_of_birth: "1990-01-01",
metadata: {
foo: "bar"
Expand All @@ -211,7 +269,7 @@
expect(response_body).to match_jsonapi_resource_schema("beneficiary")
expect(jsonapi_response_attributes).to include(
"phone_number" => "+85510999002",
"language_code" => "en",
"language_code" => "eng",
"gender" => "F",
"date_of_birth" => "1990-01-01",
"metadata" => { "foo" => "bar" }
Expand Down

0 comments on commit aed3d42

Please sign in to comment.