@@ -60,6 +60,10 @@ Consider adding a viewer to enhance the generated documentation. By itself rspec
6060
6161 gem 'raddocs'
6262
63+ or
64+
65+ gem 'apitome'
66+
6367#### spec/spec_helper.rb
6468
6569``` ruby
@@ -68,9 +72,106 @@ RspecApiDocumentation.configure do |config|
6872end
6973```
7074
75+ ####
76+ For both raddocs and apitome, start rails server. Then
77+
78+ open http://localhost:3000/docs for raddocs
79+
80+ or
81+
82+ http://localhost:3000/api/docs for apitome
83+
7184## Sample App
7285
73- See the ` example ` folder for a sample Rails app that has been documented.
86+ See the ` example ` folder for a sample Rails app that has been documented. The sample app demonstrates the : open_api format.
87+
88+ ## Example of spec file
89+
90+ ``` ruby
91+ # spec/acceptance/orders_spec.rb
92+ require ' rails_helper'
93+ require ' rspec_api_documentation/dsl'
94+ resource ' Orders' do
95+ explanation " Orders resource"
96+
97+ header " Content-Type" " application/json"
98+
99+ get ' /orders' do
100+ # This is manual way to describe complex parameters
101+ parameter :one_level_array , type: :array , items: {type: :string , enum: [' string1' ' string2' default: [' string1'
102+ parameter :two_level_array , type: :array , items: {type: :array , items: {type: :string }}
103+
104+ let(:one_level_array ) { [' string1' ' string2'
105+ let(:two_level_array ) { [[' 123' ' 234' ' 111'
106+
107+ # This is automatic way
108+ # It's possible because we extract parameters definitions from the values
109+ parameter :one_level_arr , with_example: true
110+ parameter :two_level_arr , with_example: true
111+
112+ let(:one_level_arr ) { [' value1' ' value2'
113+ let(:two_level_arr ) { [[5.1 , 3.0 ], [1.0 , 4.5 ]] }
114+
115+ context ' 200' do
116+ example_request ' Getting a list of orders' do
117+ expect(status).to eq(200 )
118+ end
119+ end
120+ end
121+
122+ put ' /orders/:id' do
123+
124+ with_options scope: :data , with_example: true do
125+ parameter :name , ' The order name' required: true
126+ parameter :amount
127+ parameter :description , ' The order description'
128+ end
129+
130+ context " 200" do
131+ let(:id ) { 1 }
132+
133+ example ' Update an order' do
134+ request = {
135+ data: {
136+ name: ' order'
137+ amount: 1 ,
138+ description: ' fast order'
139+ }
140+ }
141+
142+ # It's also possible to extract types of parameters when you pass data through `do_request` method.
143+ do_request(request)
144+
145+ expected_response = {
146+ data: {
147+ name: ' order'
148+ amount: 1 ,
149+ description: ' fast order'
150+ }
151+ }
152+ expect(status).to eq(200 )
153+ expect(response_body).to eq(expected_response)
154+ end
155+ end
156+
157+ context " 400" do
158+ let(:id ) { " a"
159+
160+ example_request ' Invalid request' do
161+ expect(status).to eq(400 )
162+ end
163+ end
164+
165+ context " 404" do
166+ let(:id ) { 0 }
167+
168+ example_request ' Order is not found' do
169+ expect(status).to eq(404 )
170+ end
171+ end
172+ end
173+ end
174+ ```
74175
75176
76177## Configuration options
@@ -306,9 +407,7 @@ paths:
306407 description: This description came from configuration file
307408 hide: true
308409```
309-
310- #### Example of spec file
311-
410+ #### Example of spec file with : open_api format
312411``` ruby
313412 resource ' Orders' do
314413 explanation " Orders resource"
0 commit comments