Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added Rswag to auto-generate swagger documentation and run request / integration tests for Platform API

Damian Legawiec488ebbdff0d0
diff --git a/.rubocop.yml b/.rubocop.yml
index 728cda8521..ae7d2bf4b1 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -63,6 +63,11 @@ Layout/DotPosition:
EnforcedStyle: trailing
Enabled: true
+Layout/SpaceInsideArrayLiteralBrackets:
+ Exclude:
+ - 'api/spec/integration/**/*.rb'
+ - 'api/lib/spree/api/testing_support/v2/platform_contexts.rb'
+
Style/FrozenStringLiteralComment:
Enabled: false
diff --git a/api/Rakefile b/api/Rakefile
index b9121c3524..e03139aee6 100644
--- a/api/Rakefile
+++ b/api/Rakefile
@@ -14,3 +14,17 @@ task :test_app do
ENV['LIB_NAME'] = 'spree/api'
Rake::Task['common:test_app'].invoke
end
+
+namespace :rswag do
+ namespace :specs do
+ desc 'Generate Swagger JSON files from integration specs'
+ RSpec::Core::RakeTask.new('swaggerize') do |t|
+ t.pattern = ENV.fetch(
+ 'PATTERN',
+ 'spec/integration/**/*_spec.rb'
+ )
+
+ t.rspec_opts = ['--format Rswag::Specs::SwaggerFormatter', '--order defined']
+ end
+ end
+end
diff --git a/api/app/controllers/spree/api/v2/platform/countries_controller.rb b/api/app/controllers/spree/api/v2/platform/countries_controller.rb
new file mode 100644
index 0000000000..cbee11276d
--- /dev/null
+++ b/api/app/controllers/spree/api/v2/platform/countries_controller.rb
@@ -0,0 +1,19 @@
+module Spree
+ module Api
+ module V2
+ module Platform
+ class CountriesController < ResourceController
+ private
+
+ def model_class
+ Spree::Country
+ end
+
+ def scope_includes
+ [:states, :zones]
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/api/app/serializers/spree/api/v2/platform/address_serializer.rb b/api/app/serializers/spree/api/v2/platform/address_serializer.rb
index 2c71d1dbb3..3593c92f88 100644
--- a/api/app/serializers/spree/api/v2/platform/address_serializer.rb
+++ b/api/app/serializers/spree/api/v2/platform/address_serializer.rb
@@ -7,6 +7,7 @@ module Spree
belongs_to :country
belongs_to :state
+ belongs_to :user
end
end
end
diff --git a/api/app/serializers/spree/api/v2/platform/user_serializer.rb b/api/app/serializers/spree/api/v2/platform/user_serializer.rb
new file mode 100644
index 0000000000..291b468f4f
--- /dev/null
+++ b/api/app/serializers/spree/api/v2/platform/user_serializer.rb
@@ -0,0 +1,21 @@
+module Spree
+ module Api
+ module V2
+ module Platform
+ class UserSerializer < BaseSerializer
+ set_type :user
+
+ attributes :email, :created_at, :updated_at
+
+ has_one :bill_address,
+ record_type: :address,
+ serializer: :address
+
+ has_one :ship_address,
+ record_type: :address,
+ serializer: :address
+ end
+ end
+ end
+ end
+end
diff --git a/api/docs/v2/platform/index.yaml b/api/docs/v2/platform/index.yaml
new file mode 100644
index 0000000000..9dad88e1c8
--- /dev/null
+++ b/api/docs/v2/platform/index.yaml
@@ -0,0 +1,599 @@
+---
+openapi: 3.0.1
+info:
+ title: Platform API V2
+ version: v2
+paths:
+ "/api/v2/platform/addresses":
+ get:
+ summary: Returns a list of an Addresses
+ tags:
+ - Addresses
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: page
+ in: query
+ example: 1
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ example: 50
+ schema:
+ type: integer
+ - name: include
+ in: query
+ descripton: 'Select which associated resources you would like to fetch, see:
+ <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
+ example: user,country,state
+ schema:
+ type: string
+ - name: filter
+ in: query
+ descripton: ''
+ example: user_id_eq=1&firstname_cont=Joh
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Records returned
+ content:
+ application/json:
+ example:
+ data:
+ - id: '1'
+ type: address
+ attributes:
+ firstname: John
+ lastname: Doe
+ address1: 10 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ state_name:
+ alternative_phone: 555-555-0199
+ company: Company
+ created_at: '2021-04-01T18:55:03.630Z'
+ updated_at: '2021-04-01T18:55:03.630Z'
+ deleted_at:
+ label:
+ relationships:
+ country:
+ data:
+ id: '1'
+ type: country
+ state:
+ data:
+ id: '1'
+ type: state
+ user:
+ data:
+ - id: '2'
+ type: address
+ attributes:
+ firstname: John
+ lastname: Doe
+ address1: 10 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ state_name:
+ alternative_phone: 555-555-0199
+ company: Company
+ created_at: '2021-04-01T18:55:03.634Z'
+ updated_at: '2021-04-01T18:55:03.634Z'
+ deleted_at:
+ label:
+ relationships:
+ country:
+ data:
+ id: '1'
+ type: country
+ state:
+ data:
+ id: '2'
+ type: state
+ user:
+ data:
+ meta:
+ count: 2
+ total_count: 2
+ total_pages: 1
+ links:
+ self: http://www.example.com/api/v2/platform/addresses?page=1&per_page=&include=&filter=
+ next: http://www.example.com/api/v2/platform/addresses?include=&page=1&per_page=
+ prev: http://www.example.com/api/v2/platform/addresses?include=&page=1&per_page=
+ last: http://www.example.com/api/v2/platform/addresses?include=&page=1&per_page=
+ first: http://www.example.com/api/v2/platform/addresses?include=&page=1&per_page=
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+ post:
+ summary: Creates an Address
+ tags:
+ - Addresses
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: include
+ in: query
+ descripton: 'Select which associated resources you would like to fetch, see:
+ <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
+ example: user,country,state
+ schema:
+ type: string
+ responses:
+ '201':
+ description: record created
+ content:
+ application/json:
+ example:
+ data:
+ id: '1'
+ type: address
+ attributes:
+ firstname: John
+ lastname: Doe
+ address1: 10 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ state_name:
+ alternative_phone: 555-555-0199
+ company: Company
+ created_at: '2021-04-01T18:55:03.796Z'
+ updated_at: '2021-04-01T18:55:03.796Z'
+ deleted_at:
+ label:
+ relationships:
+ country:
+ data:
+ id: '1'
+ type: country
+ state:
+ data:
+ id: '1'
+ type: state
+ user:
+ data:
+ id: '1'
+ type: user
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error: First Name can't be blank, Last Name can't be blank, Address
+ can't be blank, City can't be blank, Country can't be blank, Zip
+ Code can't be blank, and Phone can't be blank
+ errors:
+ firstname:
+ - can't be blank
+ lastname:
+ - can't be blank
+ address1:
+ - can't be blank
+ city:
+ - can't be blank
+ country:
+ - can't be blank
+ zipcode:
+ - can't be blank
+ phone:
+ - can't be blank
+ requestBody:
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/address_params"
+ "/api/v2/platform/addresses/{id}":
+ get:
+ summary: Returns an Address
+ tags:
+ - Addresses
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: include
+ in: query
+ descripton: 'Select which associated resources you would like to fetch, see:
+ <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
+ example: user,country,state
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Record found
+ content:
+ application/json:
+ example:
+ data:
+ id: '1'
+ type: address
+ attributes:
+ firstname: John
+ lastname: Doe
+ address1: 10 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ state_name:
+ alternative_phone: 555-555-0199
+ company: Company
+ created_at: '2021-04-01T18:55:03.828Z'
+ updated_at: '2021-04-01T18:55:03.828Z'
+ deleted_at:
+ label:
+ relationships:
+ country:
+ data:
+ id: '1'
+ type: country
+ state:
+ data:
+ id: '1'
+ type: state
+ user:
+ data:
+ '404':
+ description: Record not found
+ content:
+ application/json:
+ example:
+ error: The resource you were looking for could not be found.
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+ put:
+ summary: Updates an Address
+ tags:
+ - Addresses
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: include
+ in: query
+ descripton: 'Select which associated resources you would like to fetch, see:
+ <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
+ example: user,country,state
+ schema:
+ type: string
+ responses:
+ '200':
+ description: record updated
+ content:
+ application/json:
+ example:
+ data:
+ id: '1'
+ type: address
+ attributes:
+ firstname: Jack
+ lastname: Doe
+ address1: 10 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ state_name:
+ alternative_phone: 555-555-0199
+ company: Company
+ created_at: '2021-04-01T18:55:03.885Z'
+ updated_at: '2021-04-01T18:55:03.895Z'
+ deleted_at:
+ label:
+ relationships:
+ country:
+ data:
+ id: '1'
+ type: country
+ state:
+ data:
+ id: '1'
+ type: state
+ user:
+ data:
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error: First Name can't be blank and Last Name can't be blank
+ errors:
+ firstname:
+ - can't be blank
+ lastname:
+ - can't be blank
+ '404':
+ description: Record not found
+ content:
+ application/json:
+ example:
+ error: The resource you were looking for could not be found.
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+ requestBody:
+ content:
+ application/json:
+ schema:
+ "$ref": "#/components/schemas/address_params"
+ delete:
+ summary: Deletes an Address
+ tags:
+ - Addresses
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: Record deleted
+ '404':
+ description: Record not found
+ content:
+ application/json:
+ example:
+ error: The resource you were looking for could not be found.
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+ "/api/v2/platform/countries":
+ get:
+ summary: Returns a list of Countries
+ tags:
+ - Countries
+ security:
+ - bearer_auth: []
+ responses:
+ '200':
+ description: Records returned
+ content:
+ application/json:
+ example:
+ data:
+ - id: '1'
+ type: country
+ attributes:
+ iso_name: ISO_NAME_11
+ iso: I11
+ iso3: IS11
+ name: NAME_11
+ numcode: 840
+ states_required: false
+ updated_at: '2021-04-01T18:55:04.007Z'
+ zipcode_required: true
+ relationships:
+ states:
+ data: []
+ - id: '2'
+ type: country
+ attributes:
+ iso_name: ISO_NAME_12
+ iso: I12
+ iso3: IS12
+ name: NAME_12
+ numcode: 840
+ states_required: false
+ updated_at: '2021-04-01T18:55:04.009Z'
+ zipcode_required: true
+ relationships:
+ states:
+ data: []
+ meta:
+ count: 2
+ total_count: 2
+ total_pages: 1
+ links:
+ self: http://www.example.com/api/v2/platform/countries
+ next: http://www.example.com/api/v2/platform/countries?page=1
+ prev: http://www.example.com/api/v2/platform/countries?page=1
+ last: http://www.example.com/api/v2/platform/countries?page=1
+ first: http://www.example.com/api/v2/platform/countries?page=1
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+ "/api/v2/platform/countries/{id}":
+ get:
+ summary: Returns a Country
+ tags:
+ - Countries
+ security:
+ - bearer_auth: []
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Record found
+ content:
+ application/json:
+ example:
+ data:
+ id: '1'
+ type: country
+ attributes:
+ iso_name: ISO_NAME_15
+ iso: I15
+ iso3: IS15
+ name: NAME_15
+ numcode: 840
+ states_required: false
+ updated_at: '2021-04-01T18:55:04.046Z'
+ zipcode_required: true
+ relationships:
+ states:
+ data: []
+ '404':
+ description: Record not found
+ content:
+ application/json:
+ example:
+ error: The resource you were looking for could not be found.
+ '401':
+ description: Authentication Failed
+ content:
+ application/json:
+ example:
+ error: The access token is invalid
+servers:
+- url: https://{defaultHost}
+ variables:
+ defaultHost:
+ default: localhost:3000
+components:
+ securitySchemes:
+ bearer_auth:
+ type: http
+ scheme: bearer
+ schemas:
+ address_params:
+ type: object
+ properties:
+ country_id:
+ type: integer
+ state_id:
+ type: integer
+ state_name:
+ type: string
+ address1:
+ type: string
+ city:
+ type: string
+ zipcode:
+ type: string
+ phone:
+ type: string
+ alternative_phone:
+ type: string
+ firstname:
+ type: string
+ lastname:
+ type: string
+ label:
+ type: string
+ company:
+ type: string
+ user_id:
+ type: integer
+ resources_list:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ allOf:
+ - "$ref": "#/components/schemas/resource_properties"
+ meta:
+ type: object
+ properties:
+ count:
+ type: integer
+ total_count:
+ type: integer
+ total_pages:
+ type: integer
+ required:
+ - count
+ - total_count
+ - total_pages
+ links:
+ type: object
+ properties:
+ self:
+ type: string
+ next:
+ type: string
+ prev:
+ type: string
+ last:
+ type: string
+ first:
+ type: string
+ required:
+ - self
+ - next
+ - prev
+ - last
+ - first
+ required:
+ - data
+ - meta
+ - links
+ resource_properties:
+ type: object
+ properties:
+ id:
+ type: string
+ type:
+ type: string
+ attributes:
+ type: object
+ relationships:
+ type: object
+ required:
+ - id
+ - type
+ - attributes
+ - relationships
+ resource:
+ type: object
+ properties:
+ data:
+ "$ref": "#/components/schemas/resource_properties"
+ required:
+ - data
+ error:
+ type: object
+ properties:
+ error:
+ type: string
+ required:
+ - error
+ validation_errors:
+ type: object
+ properties:
+ error:
+ type: string
+ errors:
+ type: object
+ required:
+ - error
+ - errors
diff --git a/api/lib/spree/api/testing_support/v2/platform_contexts.rb b/api/lib/spree/api/testing_support/v2/platform_contexts.rb
index 5c6b54c6b6..ef6eafacfc 100644
--- a/api/lib/spree/api/testing_support/v2/platform_contexts.rb
+++ b/api/lib/spree/api/testing_support/v2/platform_contexts.rb
@@ -1,3 +1,9 @@
+class String
+ def articleize
+ %w(a e i o u).include?(self[0].downcase) ? "an #{self}" : "a #{self}"
+ end
+end
+
shared_context 'Platform API v2' do
let(:admin_app) { Doorkeeper::Application.find_or_create_by!(name: 'Admin Panel', scopes: 'admin', redirect_uri: '') }
let(:read_app) { Doorkeeper::Application.find_or_create_by!(name: 'Read App', scopes: 'read', redirect_uri: '') }
@@ -28,3 +34,180 @@ shared_context 'Platform API v2' do
let(:Authorization) { valid_authorization }
end
+
+shared_context 'jsonapi pagination' do
+ let(:page) { 1 }
+ let(:per_page) { '' }
+ parameter name: :page, in: :query, type: :integer, example: 1
+ parameter name: :per_page, in: :query, type: :integer, example: 50
+end
+
+JSON_API_INCLUDES_DESCRIPTION = 'Select which associated resources you would like to fetch'\
+ ', see: <a href="https://jsonapi.org/format/#fetching-includes">'\
+ 'https://jsonapi.org/format/#fetching-includes</a>'.freeze
+JSON_API_FILTER_DESCRIPTION = ''
+
+def json_api_include_parameter(example = '')
+ let(:include) { nil }
+ parameter name: :include, in: :query, type: :string, descripton: JSON_API_INCLUDES_DESCRIPTION, example: example
+end
+
+def json_api_filter_parameter(example = '')
+ let(:filter) { nil }
+ parameter name: :filter, in: :query, type: :string, descripton: JSON_API_FILTER_DESCRIPTION, example: example
+end
+
+shared_examples 'authentication failed' do
+ response '401', 'Authentication Failed' do
+ let(:Authorization) { bogus_authorization }
+ schema '$ref' => '#/components/schemas/error'
+ run_test!
+ end
+end
+
+shared_examples 'record not found' do
+ response '404', 'Record not found' do
+ let(:id) { 'invalid' }
+ schema '$ref' => '#/components/schemas/error'
+ run_test!
+ end
+end
+
+shared_examples 'record found' do
+ response '200', 'Record found' do
+ schema '$ref' => '#/components/schemas/resource'
+ run_test!
+ end
+end
+
+shared_examples 'record deleted' do
+ response '204', 'Record deleted' do
+ run_test!
+ end
+end
+
+shared_examples 'records returned' do
+ response '200', 'Records returned' do
+ schema '$ref' => '#/components/schemas/resources_list'
+ run_test!
+ end
+end
+
+shared_examples 'record created' do
+ response '201', 'record created' do
+ schema '$ref' => '#/components/schemas/resource'
+ run_test!
+ end
+end
+
+shared_examples 'record updated' do
+ response '200', 'record updated' do
+ schema '$ref' => '#/components/schemas/resource'
+ run_test!
+ end
+end
+
+shared_examples 'invalid request' do |param_name|
+ response '422', 'invalid request' do
+ let(param_name) { invalid_param_value }
+ schema '$ref' => '#/components/schemas/validation_errors'
+ run_test!
+ end
+end
+
+# index action
+shared_examples 'GET records list' do |resource_name, include_example, filter_example|
+ get "Returns a list of #{resource_name.pluralize}" do
+ tags resource_name.pluralize
+ security [ bearer_auth: [] ]
+ include_context 'jsonapi pagination'
+ json_api_include_parameter(include_example)
+ json_api_filter_parameter(filter_example)
+
+ before { records_list }
+
+ it_behaves_like 'records returned'
+ it_behaves_like 'authentication failed'
+ end
+end
+
+# show
+shared_examples 'GET record' do |resource_name, include_example|
+ get "Returns #{resource_name.articleize}" do
+ tags resource_name.pluralize
+ security [ bearer_auth: [] ]
+ parameter name: :id, in: :path, type: :string
+ json_api_include_parameter(include_example)
+
+ it_behaves_like 'record found'
+ it_behaves_like 'record not found'
+ it_behaves_like 'authentication failed'
+ end
+end
+
+# create
+shared_examples 'POST create record' do |resource_name, include_example|
+ param_name = resource_name.parameterize.to_sym
+
+ post "Creates #{resource_name.articleize}" do
+ tags resource_name.pluralize
+ consumes 'application/json'
+ security [ bearer_auth: [] ]
+ parameter name: param_name, in: :body, schema: { '$ref' => "#/components/schemas/#{param_name}_params" }
+ json_api_include_parameter(include_example)
+
+ let(param_name) { valid_create_param_value }
+
+ it_behaves_like 'record created'
+ it_behaves_like 'invalid request', param_name
+ end
+end
+
+# update
+shared_examples 'PUT update record' do |resource_name, include_example|
+ param_name = resource_name.parameterize.to_sym
+
+ put "Updates #{resource_name.articleize}" do
+ tags resource_name.pluralize
+ security [ bearer_auth: [] ]
+ consumes 'application/json'
+ parameter name: :id, in: :path, type: :string
+ parameter name: param_name, in: :body, schema: { '$ref' => "#/components/schemas/#{param_name}_params" }
+ json_api_include_parameter(include_example)
+
+ let(param_name) { valid_update_param_value }
+
+ it_behaves_like 'record updated'
+ it_behaves_like 'invalid request', param_name
+ it_behaves_like 'record not found'
+ it_behaves_like 'authentication failed'
+ end
+end
+
+# destroy
+shared_examples 'DELETE record' do |resource_name|
+ delete "Deletes #{resource_name.articleize}" do
+ tags resource_name.pluralize
+ security [ bearer_auth: [] ]
+ parameter name: :id, in: :path, type: :string
+
+ it_behaves_like 'record deleted'
+ it_behaves_like 'record not found'
+ it_behaves_like 'authentication failed'
+ end
+end
+
+shared_examples 'CRUD examples' do |resource_name, include_example, filter_example|
+ resource_path = resource_name.pluralize.parameterize
+
+ path "/api/v2/platform/#{resource_path}" do
+ include_examples 'GET records list', resource_name, include_example, filter_example
+ include_examples 'POST create record', resource_name, include_example
+ end
+
+ path "/api/v2/platform/#{resource_path}/{id}" do
+ include_examples 'GET record', resource_name, include_example
+ include_examples 'PUT update record', resource_name, include_example
+ include_examples 'DELETE record', resource_name
+ end
+end
diff --git a/api/spec/integration/api/v2/platform/addresses_spec.rb b/api/spec/integration/api/v2/platform/addresses_spec.rb
new file mode 100644
index 0000000000..c10d5549f3
--- /dev/null
+++ b/api/spec/integration/api/v2/platform/addresses_spec.rb
@@ -0,0 +1,29 @@
+require 'swagger_helper'
+
+describe 'Addresses API', swagger: true do
+ include_context 'Platform API v2'
+
+ resource_name = 'Address'
+ include_example = 'user,country,state'
+ filter_example = 'user_id_eq=1&firstname_cont=Joh'
+
+ let(:id) { create(:address).id }
+ let(:records_list) { create_list(:address, 2) }
+ let(:country) { create(:country, states_required: true) }
+ let(:state) { create(:state, country: country) }
+ let(:user) { create(:user) }
+ let(:valid_create_param_value) { build(:address, country: country, state: state, user: user).attributes }
+ let(:valid_update_param_value) do
+ {
+ firstname: 'Jack'
+ }
+ end
+ let(:invalid_param_value) do
+ {
+ firstname: '',
+ lastname: ''
+ }
+ end
+
+ include_examples 'CRUD examples', resource_name, include_example, filter_example
+end
diff --git a/api/spec/integration/api/v2/platform/countries_spec.rb b/api/spec/integration/api/v2/platform/countries_spec.rb
new file mode 100644
index 0000000000..199e1751f4
--- /dev/null
+++ b/api/spec/integration/api/v2/platform/countries_spec.rb
@@ -0,0 +1,30 @@
+require 'swagger_helper'
+
+describe 'Countries API', swagger: true do
+ include_context 'Platform API v2'
+
+ path '/api/v2/platform/countries' do
+ get 'Returns a list of Countries' do
+ tags 'Countries'
+ security [ bearer_auth: [] ]
+ before { create_list(:country, 2) }
+
+ it_behaves_like 'records returned'
+ it_behaves_like 'authentication failed'
+ end
+ end
+
+ path '/api/v2/platform/countries/{id}' do
+ let(:id) { create(:country).id }
+
+ get 'Returns a Country' do
+ tags 'Countries'
+ security [ bearer_auth: [] ]
+ parameter name: :id, in: :path, type: :string
+
+ it_behaves_like 'record found'
+ it_behaves_like 'record not found'
+ it_behaves_like 'authentication failed'
+ end
+ end
+end
diff --git a/api/spec/swagger_helper.rb b/api/spec/swagger_helper.rb
new file mode 100644
index 0000000000..dea5542d68
--- /dev/null
+++ b/api/spec/swagger_helper.rb
@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'rswag/specs'
+
+RSpec.configure do |config|
+ # Specify a root folder where Swagger JSON files are generated
+ # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
+ # to ensure that it's configured to serve Swagger from the same folder
+ config.swagger_root = Rails.root.join('../../docs').to_s # Rails.root is a dummy app
+
+ # Define one or more Swagger documents and provide global metadata for each one
+ # When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
+ # be generated at the provided relative path under swagger_root
+ # By default, the operations defined in spec files are added to the first
+ # document below. You can override this behavior by adding a swagger_doc tag to the
+ # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
+ config.swagger_docs = {
+ 'v2/platform/index.yaml' => {
+ openapi: '3.0.1',
+ info: {
+ title: 'Platform API V2',
+ version: 'v2'
+ },
+ paths: {},
+ servers: [
+ {
+ url: 'https://{defaultHost}',
+ variables: {
+ defaultHost: {
+ default: 'localhost:3000'
+ }
+ }
+ }
+ ],
+ components: {
+ securitySchemes: {
+ bearer_auth: {
+ type: :http,
+ scheme: :bearer
+ }
+ },
+ schemas: {
+ address_params: {
+ type: :object,
+ properties: {
+ country_id: { type: :integer },
+ state_id: { type: :integer },
+ state_name: { type: :string },
+ address1: { type: :string },
+ city: { type: :string },
+ zipcode: { type: :string },
+ phone: { type: :string },
+ alternative_phone: { type: :string },
+ firstname: { type: :string },
+ lastname: { type: :string },
+ label: { type: :string },
+ company: { type: :string },
+ user_id: { type: :integer }
+ }
+ },
+ resources_list: {
+ type: :object,
+ properties: {
+ data: {
+ type: :array,
+ items: {
+ allOf: [
+ { '$ref' => '#/components/schemas/resource_properties' }
+ ]
+ }
+ },
+ meta: {
+ type: :object,
+ properties: {
+ count: { type: :integer },
+ total_count: { type: :integer },
+ total_pages: { type: :integer }
+ },
+ required: %w[count total_count total_pages]
+ },
+ links: {
+ type: :object,
+ properties: {
+ self: { type: :string },
+ next: { type: :string },
+ prev: { type: :string },
+ last: { type: :string },
+ first: { type: :string }
+ },
+ required: %w[self next prev last first]
+ }
+ },
+ required: %w[data meta links]
+ },
+ resource_properties: {
+ type: :object,
+ properties: {
+ id: { type: :string },
+ type: { type: :string },
+ attributes: { type: :object },
+ relationships: { type: :object }
+ },
+ required: %w[id type attributes relationships]
+ },
+ resource: {
+ type: :object,
+ properties: {
+ data: { '$ref' => '#/components/schemas/resource_properties' },
+ },
+ required: %w[data]
+ },
+ error: {
+ type: :object,
+ properties: {
+ error: { type: :string },
+ },
+ required: %w[error]
+ },
+ validation_errors: {
+ type: :object,
+ properties: {
+ error: { type: :string },
+ errors: { type: :object }
+ },
+ required: %w[error errors]
+ }
+ }
+ }
+ }
+ }
+
+ # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'.
+ # The swagger_docs configuration option has the filename including format in
+ # the key, this may want to be changed to avoid putting yaml in json files.
+ # Defaults to json. Accepts ':json' and ':yaml'.
+ config.swagger_format = :yaml
+
+ # auto generate examples based on response
+ config.after do |example|
+ next if example.metadata[:swagger].nil?
+ next if response.nil? || response.body.blank?
+
+ example.metadata[:response][:content] = {
+ 'application/json' => {
+ example: JSON.parse(response.body, symbolize_names: true)
+ }
+ }
+ end
+end
diff --git a/api/spree_api.gemspec b/api/spree_api.gemspec
index f602aa8102..d83ce7dee0 100644
--- a/api/spree_api.gemspec
+++ b/api/spree_api.gemspec
@@ -25,6 +25,8 @@ Gem::Specification.new do |s|
s.require_paths = ["lib"]
s.add_development_dependency 'jsonapi-rspec'
+ s.add_development_dependency 'rswag-specs'
+ s.add_development_dependency 'multi_json'
s.add_dependency 'spree_core', s.version
s.add_dependency 'rabl', '~> 0.14.2'
diff --git a/common_spree_dependencies.rb b/common_spree_dependencies.rb
index 7474572eae..37dc1fae41 100644
--- a/common_spree_dependencies.rb
+++ b/common_spree_dependencies.rb
@@ -25,10 +25,12 @@ group :test do
gem 'database_cleaner', '~> 1.3'
gem 'email_spec'
gem 'factory_bot_rails', '~> 6.0'
+ gem 'multi_json'
gem 'rspec-activemodel-mocks', '~> 1.0'
gem 'rspec-rails', '~> 4.0'
gem 'rspec-retry'
gem 'rspec_junit_formatter'
+ gem 'rswag-specs'
gem 'jsonapi-rspec'
gem 'simplecov', '0.17.1'
gem 'webmock', '~> 3.7'