diff --git a/Gemfile.lock b/Gemfile.lock index 73364087..31f46c6b 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -34,7 +34,7 @@ GEM xpath (~> 2.0) childprocess (0.5.9) ffi (~> 1.0, >= 1.0.11) - coderay (1.1.0) + coderay (1.1.2) contracts (0.13.0) crack (0.4.3) safe_yaml (~> 1.0.0) @@ -60,13 +60,13 @@ GEM hashdiff (0.2.3) httpclient (2.7.1) i18n (0.7.0) - inch (0.7.0) + inch (0.8.0) pry sparkr (>= 0.2.0) term-ansicolor - yard (~> 0.8.7.5) + yard (~> 0.9.12) json (1.8.6) - method_source (0.8.2) + method_source (0.9.0) mime-types (3.0) mime-types-data (~> 3.2015) mime-types-data (3.2015.1120) @@ -76,12 +76,11 @@ GEM multi_test (0.1.2) multipart-post (2.0.0) mustache (1.0.3) - nokogiri (1.8.1) + nokogiri (1.8.4) mini_portile2 (~> 2.3.0) - pry (0.10.3) + pry (0.11.3) coderay (~> 1.1.0) - method_source (~> 0.8.1) - slop (~> 3.4) + method_source (~> 0.9.0) rack (1.6.4) rack-oauth2 (1.2.2) activesupport (>= 2.3) @@ -115,9 +114,8 @@ GEM rack (~> 1.5) rack-protection (~> 1.4) tilt (>= 1.3, < 3) - slop (3.6.0) sparkr (0.4.1) - term-ansicolor (1.3.2) + term-ansicolor (1.6.0) tins (~> 1.0) thin (1.6.4) daemons (~> 1.0, >= 1.0.9) @@ -126,7 +124,7 @@ GEM thor (0.19.1) thread_safe (0.3.5) tilt (2.0.2) - tins (1.8.2) + tins (1.16.3) tzinfo (1.2.2) thread_safe (~> 0.1) webmock (1.22.6) @@ -135,7 +133,7 @@ GEM hashdiff xpath (2.0.0) nokogiri (~> 1.3) - yard (0.8.7.6) + yard (0.9.15) PLATFORMS ruby @@ -147,6 +145,7 @@ DEPENDENCIES fakefs (~> 0.4) faraday (~> 0.9, >= 0.9.0) inch + nokogiri (~> 1.8, >= 1.8.2) rack-oauth2 (~> 1.2.2, >= 1.0.7) rack-test (~> 0.6.2) rake (~> 10.1) @@ -155,6 +154,7 @@ DEPENDENCIES sinatra (~> 1.4, >= 1.4.4) thin (~> 1.6, >= 1.6.3) webmock (~> 1.7) + yard (>= 0.9.11) BUNDLED WITH - 1.16.1 + 1.16.3 diff --git a/README.md b/README.md index d1e02947..f6b00f65 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,10 @@ Consider adding a viewer to enhance the generated documentation. By itself rspec gem 'raddocs' + or + + gem 'apitome' + #### spec/spec_helper.rb ```ruby @@ -68,9 +72,106 @@ RspecApiDocumentation.configure do |config| end ``` +#### +For both raddocs and apitome, start rails server. Then + + open http://localhost:3000/docs for raddocs + + or + + http://localhost:3000/api/docs for apitome + ## Sample App -See the `example` folder for a sample Rails app that has been documented. +See the `example` folder for a sample Rails app that has been documented. The sample app demonstrates the :open_api format. + +## Example of spec file + +```ruby + # spec/acceptance/orders_spec.rb + require 'rails_helper' + require 'rspec_api_documentation/dsl' + resource 'Orders' do + explanation "Orders resource" + + header "Content-Type", "application/json" + + get '/orders' do + # This is manual way to describe complex parameters + parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1'] + parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}} + + let(:one_level_array) { ['string1', 'string2'] } + let(:two_level_array) { [['123', '234'], ['111']] } + + # This is automatic way + # It's possible because we extract parameters definitions from the values + parameter :one_level_arr, with_example: true + parameter :two_level_arr, with_example: true + + let(:one_level_arr) { ['value1', 'value2'] } + let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] } + + context '200' do + example_request 'Getting a list of orders' do + expect(status).to eq(200) + end + end + end + + put '/orders/:id' do + + with_options scope: :data, with_example: true do + parameter :name, 'The order name', required: true + parameter :amount + parameter :description, 'The order description' + end + + context "200" do + let(:id) { 1 } + + example 'Update an order' do + request = { + data: { + name: 'order', + amount: 1, + description: 'fast order' + } + } + + # It's also possible to extract types of parameters when you pass data through `do_request` method. + do_request(request) + + expected_response = { + data: { + name: 'order', + amount: 1, + description: 'fast order' + } + } + expect(status).to eq(200) + expect(response_body).to eq(expected_response) + end + end + + context "400" do + let(:id) { "a" } + + example_request 'Invalid request' do + expect(status).to eq(400) + end + end + + context "404" do + let(:id) { 0 } + + example_request 'Order is not found' do + expect(status).to eq(404) + end + end + end + end +``` ## Configuration options @@ -306,9 +407,7 @@ paths: description: This description came from configuration file hide: true ``` - -#### Example of spec file - +#### Example of spec file with :open_api format ```ruby resource 'Orders' do explanation "Orders resource" diff --git a/example/Gemfile b/example/Gemfile index 53112786..cacf5aff 100644 --- a/example/Gemfile +++ b/example/Gemfile @@ -6,7 +6,7 @@ gem 'rack-cors', :require => 'rack/cors' gem 'rails', '4.2.5.1' gem 'sqlite3' gem 'spring', group: :development -gem 'raddocs', :github => "smartlogic/raddocs" +gem 'raddocs', '0.4.0' group :test, :development do gem 'byebug' diff --git a/example/Gemfile.lock b/example/Gemfile.lock index 32919b0f..fd2e4eef 100644 --- a/example/Gemfile.lock +++ b/example/Gemfile.lock @@ -1,12 +1,3 @@ -GIT - remote: git://github.com/smartlogic/raddocs.git - revision: 9cf49c1ef3b3d7dc3bf8e19ef75021040df04652 - specs: - raddocs (0.4.0) - haml (~> 4.0, >= 4.0.4) - json (~> 1.8, >= 1.8.1) - sinatra (~> 1.3, >= 1.3.0) - PATH remote: .. specs: @@ -62,7 +53,7 @@ GEM erubis (2.7.0) globalid (0.3.6) activesupport (>= 4.1.0) - haml (4.0.5) + haml (4.0.7) tilt i18n (0.7.0) json (1.8.3) @@ -78,10 +69,14 @@ GEM mini_portile2 (~> 2.0.0.rc2) rack (1.6.4) rack-cors (0.4.1) - rack-protection (1.5.3) + rack-protection (1.5.5) rack rack-test (0.6.3) rack (>= 1.0) + raddocs (0.4.0) + haml (~> 4.0, >= 4.0.4) + json (~> 1.8, >= 1.8.1) + sinatra (~> 1.3, >= 1.3.0) rails (4.2.5.1) actionmailer (= 4.2.5.1) actionpack (= 4.2.5.1) @@ -127,10 +122,10 @@ GEM rspec-mocks (~> 3.0.0) rspec-support (~> 3.0.0) rspec-support (3.0.4) - sinatra (1.4.5) - rack (~> 1.4) + sinatra (1.4.8) + rack (~> 1.5) rack-protection (~> 1.4) - tilt (~> 1.3, >= 1.3.4) + tilt (>= 1.3, < 3) spring (1.1.3) sprockets (3.5.2) concurrent-ruby (~> 1.0) @@ -142,7 +137,7 @@ GEM sqlite3 (1.3.9) thor (0.19.1) thread_safe (0.3.5) - tilt (1.4.1) + tilt (2.0.8) tzinfo (1.2.2) thread_safe (~> 0.1) @@ -153,7 +148,7 @@ DEPENDENCIES awesome_print byebug rack-cors - raddocs! + raddocs (= 0.4.0) rails (= 4.2.5.1) rspec-rails rspec_api_documentation! @@ -164,4 +159,4 @@ RUBY VERSION ruby 2.3.3p222 BUNDLED WITH - 1.16.2 + 1.16.3 diff --git a/example/spec/acceptance_helper.rb b/example/spec/acceptance_helper.rb index af483744..7b4e69f4 100644 --- a/example/spec/acceptance_helper.rb +++ b/example/spec/acceptance_helper.rb @@ -3,7 +3,7 @@ require 'rspec_api_documentation/dsl' RspecApiDocumentation.configure do |config| - config.format = [:open_api] + config.format = [:open_api, :html] config.curl_host = 'http://localhost:3000' config.api_name = "Example App API" config.api_explanation = "API Example Description" diff --git a/rspec_api_documentation.gemspec b/rspec_api_documentation.gemspec index cc975926..ed5edf7d 100644 --- a/rspec_api_documentation.gemspec +++ b/rspec_api_documentation.gemspec @@ -30,6 +30,8 @@ Gem::Specification.new do |s| s.add_development_dependency "rspec-its", "~> 1.0" s.add_development_dependency "faraday", "~> 0.9", ">= 0.9.0" s.add_development_dependency "thin", "~> 1.6", ">= 1.6.3" + s.add_development_dependency "nokogiri", "~> 1.8", ">= 1.8.2" + s.add_development_dependency "yard", ">= 0.9.11" s.files = Dir.glob("lib/**/*") + Dir.glob("templates/**/*") s.require_path = "lib"