{"id":13463177,"url":"https://github.com/zipmark/rspec_api_documentation","last_synced_at":"2025-05-13T23:03:56.856Z","repository":{"id":1856516,"uuid":"2781355","full_name":"zipmark/rspec_api_documentation","owner":"zipmark","description":"Automatically generate API documentation from RSpec","archived":false,"fork":false,"pushed_at":"2024-08-17T08:03:42.000Z","size":1709,"stargazers_count":1455,"open_issues_count":110,"forks_count":367,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-30T12:16:56.010Z","etag":null,"topics":["api","rspec","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mozilla/webpay","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zipmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-11-15T16:12:21.000Z","updated_at":"2025-04-02T02:26:11.000Z","dependencies_parsed_at":"2024-01-03T01:18:53.066Z","dependency_job_id":"37ebe986-9ca9-464e-9a33-6eafa221267f","html_url":"https://github.com/zipmark/rspec_api_documentation","commit_stats":{"total_commits":762,"total_committers":100,"mean_commits":7.62,"dds":0.5433070866141732,"last_synced_commit":"d32bf17932a379052e8bb7540fc29ce7e72712ae"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zipmark%2Frspec_api_documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zipmark%2Frspec_api_documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zipmark%2Frspec_api_documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zipmark%2Frspec_api_documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zipmark","download_url":"https://codeload.github.com/zipmark/rspec_api_documentation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254040337,"owners_count":22004510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","rspec","ruby"],"created_at":"2024-07-31T13:00:47.405Z","updated_at":"2025-05-13T23:03:56.830Z","avatar_url":"https://github.com/zipmark.png","language":"Ruby","readme":"[![Code Climate](https://codeclimate.com/github/zipmark/rspec_api_documentation/badges/gpa.svg)](https://codeclimate.com/github/zipmark/rspec_api_documentation)\n[![Inline docs](https://inch-ci.org/github/zipmark/rspec_api_documentation.svg?branch=master)](https://inch-ci.org/github/zipmark/rspec_api_documentation)\n[![Gem Version](https://badge.fury.io/rb/rspec_api_documentation.svg)](https://badge.fury.io/rb/rspec_api_documentation)\n\n# RSpec API Doc Generator\n\nGenerate pretty API docs for your Rails APIs.\n\nCheck out a [sample](http://rad-example.herokuapp.com).\n\n## Changes\n\nPlease see the wiki for latest [changes](https://github.com/zipmark/rspec_api_documentation/wiki/Changes).\n\n## Installation\n\nAdd rspec_api_documentation to your Gemfile\n\n    gem 'rspec_api_documentation'\n\nBundle it!\n\n    $ bundle install\n\nSet up specs.\n\n    $ mkdir spec/acceptance\n    $ vim spec/acceptance/orders_spec.rb\n\n```ruby\nrequire 'rails_helper'\nrequire 'rspec_api_documentation/dsl'\n\nresource \"Orders\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      do_request\n\n      expect(status).to eq 200\n    end\n  end\nend\n```\n\nGenerate the docs!\n\n    $ rake docs:generate\n    $ open doc/api/index.html\n\n### Viewers\n\nConsider adding a viewer to enhance the generated documentation. By itself rspec_api_documentation will generate very simple HTML. All viewers use the generated JSON.\n\n* [Raddocs](http://github.com/smartlogic/raddocs/) - Sinatra app\n* [Apitome](https://github.com/modeset/apitome) - Rails engine\n\n#### Gemfile\n\n    gem 'raddocs'\n\n    or \n\n    gem 'apitome'\n\n#### spec/spec_helper.rb\n\n```ruby\nRspecApiDocumentation.configure do |config|\n  config.format = :json\nend\n```\n\n####\nFor both raddocs and apitome, start rails server. Then\n\n    open http://localhost:3000/docs for raddocs\n\n    or\n\n    http://localhost:3000/api/docs for apitome\n\n## Sample App\n\nSee the `example` folder for a sample Rails app that has been documented.  The sample app demonstrates the :open_api format.\n\n## Example of spec file\n\n```ruby\n  # spec/acceptance/orders_spec.rb\n  require 'rails_helper'\n  require 'rspec_api_documentation/dsl'\n  resource 'Orders' do\n    explanation \"Orders resource\"\n    \n    header \"Content-Type\", \"application/json\"\n\n    get '/orders' do\n      # This is manual way to describe complex parameters\n      parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']\n      parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}\n      \n      let(:one_level_array) { ['string1', 'string2'] }\n      let(:two_level_array) { [['123', '234'], ['111']] }\n\n      # This is automatic way\n      # It's possible because we extract parameters definitions from the values\n      parameter :one_level_arr, with_example: true\n      parameter :two_level_arr, with_example: true\n\n      let(:one_level_arr) { ['value1', 'value2'] }\n      let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }\n\n      context '200' do\n        example_request 'Getting a list of orders' do\n          expect(status).to eq(200)\n        end\n      end\n    end\n\n    put '/orders/:id' do\n\n      with_options scope: :data, with_example: true do\n        parameter :name, 'The order name', required: true\n        parameter :amount\n        parameter :description, 'The order description'\n      end\n\n      context \"200\" do\n        let(:id) { 1 }\n\n        example 'Update an order' do\n          request = {\n            data: {\n              name: 'order',\n              amount: 1,\n              description: 'fast order'\n            }\n          }\n          \n          # It's also possible to extract types of parameters when you pass data through `do_request` method.\n          do_request(request)\n          \n          expected_response = {\n            data: {\n              name: 'order',\n              amount: 1,\n              description: 'fast order'\n            }\n          }\n          expect(status).to eq(200)\n          expect(response_body).to eq(expected_response)\n        end\n      end\n\n      context \"400\" do\n        let(:id) { \"a\" }\n\n        example_request 'Invalid request' do\n          expect(status).to eq(400)\n        end\n      end\n      \n      context \"404\" do\n        let(:id) { 0 }\n        \n        example_request 'Order is not found' do\n          expect(status).to eq(404)\n        end\n      end\n    end\n  end\n```\n\n\n## Configuration options\n```ruby\n# Values listed are the default values\nRspecApiDocumentation.configure do |config|\n  # Set the application that Rack::Test uses\n  config.app = Rails.application\n\n  # Used to provide a configuration for the specification (supported only by 'open_api' format for now) \n  config.configurations_dir = Rails.root.join(\"doc\", \"configurations\", \"api\")\n\n  # Output folder\n  # **WARNING*** All contents of the configured directory will be cleared, use a dedicated directory.\n  config.docs_dir = Rails.root.join(\"doc\", \"api\")\n\n  # An array of output format(s).\n  # Possible values are :json, :html, :combined_text, :combined_json,\n  #   :json_iodocs, :textile, :markdown, :append_json, :slate,\n  #   :api_blueprint, :open_api\n  config.format = [:html]\n\n  # Location of templates\n  config.template_path = \"inside of the gem\"\n\n  # Filter by example document type\n  config.filter = :all\n\n  # Filter by example document type\n  config.exclusion_filter = nil\n\n  # Used when adding a cURL output to the docs\n  config.curl_host = nil\n\n  # Used when adding a cURL output to the docs\n  # Allows you to filter out headers that are not needed in the cURL request,\n  # such as \"Host\" and \"Cookie\". Set as an array.\n  config.curl_headers_to_filter = nil\n\n  # By default, when these settings are nil, all headers are shown,\n  # which is sometimes too chatty. Setting the parameters to an\n  # array of headers will render *only* those headers.\n  config.request_headers_to_include = nil\n  config.response_headers_to_include = nil\n\n  # By default examples and resources are ordered by description. Set to true keep\n  # the source order.\n  config.keep_source_order = false\n\n  # Change the name of the API on index pages\n  config.api_name = \"API Documentation\"\n  \n  # Change the description of the API on index pages\n  config.api_explanation = \"API Description\"\n\n  # Redefine what method the DSL thinks is the client\n  # This is useful if you need to `let` your own client, most likely a model.\n  config.client_method = :client\n\n  # Change the IODocs writer protocol\n  config.io_docs_protocol = \"http\"\n\n  # You can define documentation groups as well. A group allows you generate multiple\n  # sets of documentation.\n  config.define_group :public do |config|\n    # By default the group's doc_dir is a subfolder under the parent group, based\n    # on the group's name.\n    # **WARNING*** All contents of the configured directory will be cleared, use a dedicated directory.\n    config.docs_dir = Rails.root.join(\"doc\", \"api\", \"public\")\n\n    # Change the filter to only include :public examples\n    config.filter = :public\n  end\n\n  # Change how the post body is formatted by default, you can still override by `raw_post`\n  # Can be :json, :xml, or a proc that will be passed the params\n  config.request_body_formatter = Proc.new { |params| params }\n\n  # Change how the response body is formatted by default\n  # Is proc that will be called with the response_content_type \u0026 response_body\n  # by default, a response body that is likely to be binary is replaced with the string\n  # \"[binary data]\" regardless of the media type.  Otherwise, a response_content_type of `application/json` is pretty formatted.\n  config.response_body_formatter = Proc.new { |response_content_type, response_body| response_body }\n\n  # Change the embedded style for HTML output. This file will not be processed by\n  # RspecApiDocumentation and should be plain CSS.\n  config.html_embedded_css_file = nil\n\n  # Removes the DSL method `status`, this is required if you have a parameter named status\n  # In this case you can assert response status with `expect(response_status).to eq 200`\n  config.disable_dsl_status!\n\n  # Removes the DSL method `method`, this is required if you have a parameter named method\n  config.disable_dsl_method!\nend\n```\n\n## Format\n\n* **json**: Generates an index file and example files in JSON.\n* **html**: Generates an index file and example files in HTML.\n* **combined_text**: Generates a single file for each resource. Used by [Raddocs](http://github.com/smartlogic/raddocs) for command line docs.\n* **combined_json**: Generates a single file for all examples.\n* **json_iodocs**: Generates [I/O Docs](http://www.mashery.com/product/io-docs) style documentation.\n* **textile**: Generates an index file and example files in Textile.\n* **markdown**: Generates an index file and example files in Markdown.\n* **api_blueprint**: Generates an index file and example files in [APIBlueprint](https://apiblueprint.org).\n* **append_json**: Lets you selectively run specs without destroying current documentation. See section below.\n* **slate**: Builds markdown files that can be used with [Slate](https://github.com/lord/slate), a beautiful static documentation builder.\n* **open_api**: Generates [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (OAS) (Current supported version is 2.0). Can be used for [Swagger-UI](https://swagger.io/tools/swagger-ui/) \n\n### append_json\n\nThis format cannot be run with other formats as they will delete the entire documentation folder upon each run. This format appends new examples to the index file, and writes all run examples in the correct folder.\n\nBelow is a rake task that allows this format to be used easily.\n\n```ruby\nRSpec::Core::RakeTask.new('docs:generate:append', :spec_file) do |t, task_args|\n  if spec_file = task_args[:spec_file]\n    ENV[\"DOC_FORMAT\"] = \"append_json\"\n  end\n  t.pattern    = spec_file || 'spec/acceptance/**/*_spec.rb'\n  t.rspec_opts = [\"--format RspecApiDocumentation::ApiFormatter\"]\nend\n```\n\nAnd in your `spec/spec_helper.rb`:\n\n```ruby\nENV[\"DOC_FORMAT\"] ||= \"json\"\n\nRspecApiDocumentation.configure do |config|\n  config.format    = ENV[\"DOC_FORMAT\"]\nend\n```\n\n```bash\nrake docs:generate:append[spec/acceptance/orders_spec.rb]\n```\n\nThis will update the current index's examples to include any in the `orders_spec.rb` file. Any examples inside will be rewritten.\n\n### api_blueprint\n\nThis [format](https://apiblueprint.org) (APIB) has additional functions:\n\n* `route`: APIB groups URLs together and then below them are HTTP verbs.\n\n  ```ruby\n  route \"/orders\", \"Orders Collection\" do\n    get \"Returns all orders\" do\n      # ...\n    end\n\n    delete \"Deletes all orders\" do\n      # ...\n    end\n  end\n  ```\n\n  If you don't use `route`, then param in `get(param)` should be an URL as\n  states in the rest of this documentation.\n\n* `attribute`: APIB has attributes besides parameters. Use attributes exactly\n  like you'd use `parameter` (see documentation below).\n  \n### open_api \n\nThis [format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (OAS) has additional functions:\n\n* `authentication(type, value, opts = {})` ([Security schema object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-scheme-object))\n\n    The values will be passed through header of the request. Option `name` has to be provided for `apiKey`. \n    \n    * `authentication :basic, 'Basic Key'`\n    * `authentication :apiKey, 'Api Key', name: 'API_AUTH', description: 'Some description'`\n    \n    You could pass `Symbol` as value. In this case you need to define a `let` with the same name.\n    \n    ```\n    authentication :apiKey, :api_key\n    let(:api_key) { some_value } \n    ```\n    \n* `route_summary(text)` and `route_description(text)`. ([Operation object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object)) \n\n    These two simplest methods accept `String`. \n    It will be used for route's `summary` and `description`. \n    \n* Several new options on `parameter` helper.\n\n    - `with_example: true`. This option will adjust your example of the parameter with the passed value.\n    - `example: \u003cvalue\u003e`. Will provide a example value for the parameter.\n    - `default: \u003cvalue\u003e`. Will provide a default value for the parameter.\n    - `minimum: \u003cinteger\u003e`. Will setup upper limit for your parameter. \n    - `maximum: \u003cinteger\u003e`. Will setup lower limit for your parameter.\n    - `enum: [\u003cvalue\u003e, \u003cvalue\u003e, ..]`. Will provide a pre-defined list of possible values for your parameter.\n    - `type: [:file, :array, :object, :boolean, :integer, :number, :string]`. Will set a type for the parameter. Most of the type you don't need to provide this option manually. We extract types from values automatically.\n\n\nYou also can provide a configuration file in YAML or JSON format with some manual configs. \nThe file should be placed in `configurations_dir` folder with the name `open_api.yml` or `open_api.json`. \nIn this file you able to manually **hide** some endpoints/resources you want to hide from generated API specification but still want to test. \nIt's also possible to pass almost everything to the specification builder manually.\n\n#### Example of configuration file\n\n```yaml\nswagger: '2.0'\ninfo:\n  title: OpenAPI App\n  description: This is a sample server.\n  termsOfService: 'http://open-api.io/terms/'\n  contact:\n    name: API Support\n    url: 'http://www.open-api.io/support'\n    email: support@open-api.io\n  license:\n    name: Apache 2.0\n    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'\n  version: 1.0.0\nhost: 'localhost:3000'\nschemes:\n  - http\n  - https\nconsumes:\n  - application/json\n  - application/xml\nproduces:\n  - application/json\n  - application/xml\npaths: \n  /orders:\n    hide: true\n  /instructions:\n    hide: false\n    get:\n      description: This description came from configuration file\n      hide: true\n```\n#### Example of spec file with :open_api format\n```ruby\n  resource 'Orders' do\n    explanation \"Orders resource\"\n    \n    authentication :apiKey, :api_key, description: 'Private key for API access', name: 'HEADER_KEY'\n    header \"Content-Type\", \"application/json\"\n    \n    let(:api_key) { generate_api_key }\n\n    get '/orders' do\n      route_summary \"This URL allows users to interact with all orders.\"\n      route_description \"Long description.\"\n\n      # This is manual way to describe complex parameters\n      parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']\n      parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}\n      \n      let(:one_level_array) { ['string1', 'string2'] }\n      let(:two_level_array) { [['123', '234'], ['111']] }\n\n      # This is automatic way\n      # It's possible because we extract parameters definitions from the values\n      parameter :one_level_arr, with_example: true\n      parameter :two_level_arr, with_example: true\n\n      let(:one_level_arr) { ['value1', 'value2'] }\n      let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }\n\n      context '200' do\n        example_request 'Getting a list of orders' do\n          expect(status).to eq(200)\n          expect(response_body).to eq(\u003cresponse\u003e)\n        end\n      end\n    end\n\n    put '/orders/:id' do\n      route_summary \"This is used to update orders.\"\n\n      with_options scope: :data, with_example: true do\n        parameter :name, 'The order name', required: true\n        parameter :amount\n        parameter :description, 'The order description'\n      end\n\n      context \"200\" do\n        let(:id) { 1 }\n\n        example 'Update an order' do\n          request = {\n            data: {\n              name: 'order',\n              amount: 1,\n              description: 'fast order'\n            }\n          }\n          \n          # It's also possible to extract types of parameters when you pass data through `do_request` method.\n          do_request(request)\n          \n          expected_response = {\n            data: {\n              name: 'order',\n              amount: 1,\n              description: 'fast order'\n            }\n          }\n          expect(status).to eq(200)\n          expect(response_body).to eq(\u003cresponse\u003e)\n        end\n      end\n\n      context \"400\" do\n        let(:id) { \"a\" }\n\n        example_request 'Invalid request' do\n          expect(status).to eq(400)\n        end\n      end\n      \n      context \"404\" do\n        let(:id) { 0 }\n        \n        example_request 'Order is not found' do\n          expect(status).to eq(404)\n        end\n      end\n    end\n  end\n```\n\n## Filtering and Exclusion\n\nrspec_api_documentation lets you determine which examples get outputted into the final documentation.\nAll filtering is done via the `:document` metadata key.\nYou tag examples with either a single symbol or an array of symbols.\n`:document` can also be false, which will make sure it does not get outputted.\n\n```ruby\nresource \"Account\" do\n  get \"/accounts\" do\n    parameter :page, \"Page to view\"\n\n    # default :document is :all\n    example \"Get a list of all accounts\" do\n      do_request\n      expect(status).to eq 200\n    end\n\n    # Don't actually document this example, purely for testing purposes\n    example \"Get a list on page 2\", :document =\u003e false do\n      do_request(:page =\u003e 2)\n      expect(status).to eq 404\n    end\n\n    # With example_request, you can't change the :document\n    example_request \"Get a list on page 3\", :page =\u003e 3 do\n      expect(status).to eq 404\n    end\n  end\n\n  post \"/accounts\" do\n    parameter :email, \"User email\"\n\n    example \"Creating an account\", :document =\u003e :private do\n      do_request(:email =\u003e \"eric@example.com\")\n      expect(status).to eq 201\n    end\n\n    example \"Creating an account - errors\", :document =\u003e [:private, :developers] do\n      do_request\n      expect(status).to eq 422\n    end\n  end\nend\n```\n\n```ruby\n# All documents will be generated into the top folder, :document =\u003e false\n# examples will never be generated.\nRspecApiDocumentation.configure do |config|\n  # Exclude only document examples marked as 'private'\n  config.define_group :non_private do |config|\n    config.exclusion_filter = :private\n  end\n\n  # Only document examples marked as 'public'\n  config.define_group :public do |config|\n    config.filter = :public\n  end\n\n  # Only document examples marked as 'developer'\n  config.define_group :developers do |config|\n    config.filter = :developers\n  end\nend\n```\n\n## DSL\n\n### Require the DSL\n\nAt the beginning of each acceptance/*_spec.rb file, make sure to require the following to pull in the DSL definitions:\n\n```ruby\nrequire 'rspec_api_documentation/dsl'\n```\n\n\n### Example Group Methods\n\n\n#### resource\n\nCreate a set of documentation examples that go together. Acts as a describe block.\n\n```ruby\nresource \"Orders\" do\nend\n```\n\n#### get, head, post, put, delete, patch\n\nThe method that will be sent along with the url.\n\n```ruby\nresource \"Orders\" do\n  post \"/orders\" do\n  end\n\n  get \"/orders\" do\n  end\n\n  head \"/orders\" do\n  end\n\n  put \"/orders/:id\" do\n    let(:id) { order.id }\n\n    example \"Get an order\" do\n      expect(path).to eq \"/orders/1\" # `:id` is replaced with the value of `id`\n    end\n  end\n\n  delete \"/orders/:id\" do\n  end\n\n  patch \"/orders/:id\" do\n  end\nend\n```\n\n#### example\n\nThis is just RSpec's built in example method, we hook into the metadata surrounding it. `it` could also be used.\n\n```ruby\nresource \"Orders\" do\n  post \"/orders\" do\n    example \"Creating an order\" do\n      do_request\n      # make assertions\n    end\n  end\nend\n```\n\n#### example_request\n\nThe same as example, except it calls `do_request` as the first step. Only assertions are required in the block.\n\nSimilar to `do_request` you can pass in a hash as the last parameter that will be passed along to `do_request` as extra parameters. These will _not_ become metadata like with `example`.\n\n```ruby\nresource \"Orders\" do\n  parameter :name, \"Order name\"\n\n  post \"/orders\" do\n    example_request \"Creating an order\", :name =\u003e \"Other name\" do\n      # make assertions\n    end\n  end\nend\n```\n\n#### explanation\n\nThis method takes a string representing a detailed explanation of the example.\n\n```ruby\nresource \"Orders\" do\n  post \"/orders\" do\n    example \"Creating an order\" do\n      explanation \"This method creates a new order.\"\n      do_request\n      # make assertions\n    end\n  end\nend\n```\n\nA resource can also have an explanation.\n\n```ruby\nresource \"Orders\" do\n  explanation \"Orders are top-level business objects. They can be created by a POST request\"\n  post \"/orders\" do\n    example \"Creating an order\" do\n      explanation \"This method creates a new order.\"\n      do_request\n      # make assertions\n    end\n  end\nend\n```\n\n\n#### header\n\nThis method takes the header name and value. The value can be a string or a symbol. If it is a symbol it will `send` the symbol, allowing you to `let` header values.\n\n```ruby\nresource \"Orders\" do\n  header \"Accept\", \"application/json\"\n  header \"X-Custom\", :custom_header\n\n  let(:custom_header) { \"dynamic\" }\n\n  get \"/orders\" do\n    example_request \"Headers\" do\n      expect(headers).to eq { \"Accept\" =\u003e \"application/json\", \"X-Custom\" =\u003e \"dynamic\" }\n    end\n  end\nend\n```\n\n#### parameter\n\nThis method takes the parameter name, a description, and an optional hash of extra metadata that can be displayed in Raddocs as extra columns. If a method with the parameter name exists, e.g. a `let`, it will send the returned value up to the server as URL encoded data.\n\nSpecial values:\n\n* `:required =\u003e true` Will display a red '*' to show it's required\n* `:scope =\u003e :the_scope` Will scope parameters in the hash, scoping can be nested. See example\n* `:method =\u003e :method_name` Will use specified method as a parameter value\n\nRetrieving of parameter value goes through several steps:\n1. if `method` option is defined and test case responds to this method then this method is used;\n2. if test case responds to scoped method then this method is used;\n3. overwise unscoped method is used.\n\n```ruby\nresource \"Orders\" do\n  parameter :auth_token, \"Authentication Token\"\n\n  let(:auth_token) { user.authentication_token }\n\n  post \"/orders\" do\n    parameter :name, \"Order Name\", :required =\u003e true, :scope =\u003e :order\n    parameter :item, \"Order items\", :scope =\u003e :order\n    parameter :item_id, \"Item id\", :scope =\u003e [:order, :item], method: :custom_item_id\n\n    let(:name) { \"My Order\" }\n    # OR let(:order_name) { \"My Order\" }\n    let(:item_id) { 1 }\n    # OR let(:custom_item_id) { 1 }\n    # OR let(:order_item_item_id) { 1 }\n\n    example \"Creating an order\" do\n      expect(params).to eq({\n        :order =\u003e {\n          :name =\u003e \"My Order\",\n          :item =\u003e {\n            :item_id =\u003e 1,\n          }\n        },\n        :auth_token =\u003e auth_token,\n      })\n    end\n  end\nend\n```\n\n#### response_field\n\nThis method takes the response field name, a description, and an optional hash of extra metadata that can be displayed in Raddocs as extra columns.\n\nSpecial values:\n* `:scope =\u003e :the_scope` Will scope the response field in the hash\n\n```ruby\nresource \"Orders\" do\n  response_field :page, \"Current page\"\n\n  get \"/orders\" do\n    example_request \"Getting orders\" do\n      expect(response_body).to eq({ :page =\u003e 1 }.to_json)\n    end\n  end\nend\n```\n\n\nYou can also group metadata using [with_options](http://api.rubyonrails.org/classes/Object.html#method-i-with_options) to factor out duplications.\n\n```ruby\nresource \"Orders\" do\n  post \"/orders\" do\n\n    with_options :scope =\u003e :order, :required =\u003e true do\n      parameter :name, \"Order Name\"\n      parameter :item, \"Order items\"\n    end\n\n    with_options :scope =\u003e :order do\n      response_field :id, \"Order ID\"\n      response_field :status, \"Order status\"\n    end\n\n    let(:name) { \"My Order\" }\n    let(:item_id) { 1 }\n\n    example \"Creating an order\" do\n      expect(status).to be 201\n    end\n  end\nend\n```\n\n#### callback\n\nThis is complicated, see [relish docs](https://www.relishapp.com/zipmark/rspec-api-documentation/docs/document-callbacks).\n\n#### trigger_callback\n\nPass this method a block which, when evaluated, will cause the application to make a request to `callback_url`.\n\n### Example methods\n\n#### callback_url\n\nDefines the destination of the callback.\n\nFor an example, see [relish docs](https://www.relishapp.com/zipmark/rspec-api-documentation/docs/document-callbacks).\n\n#### client\n\nReturns the test client which makes requests and documents the responses.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      # Create an order via the API instead of via factories\n      client.post \"/orders\", order_hash\n\n      do_request\n\n      expect(status).to eq 200\n    end\n  end\nend\n```\n\n#### do_callback\n\nThis will evaluate the block passed to `trigger_callback`, which should cause the application under test to make a callback request. See [relish docs](https://www.relishapp.com/zipmark/rspec-api-documentation/docs/document-callbacks).\n\n#### do_request\n\nSends the request to the app with any parameters and headers defined.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      do_request\n\n      expect(status).to eq 200\n    end\n  end\nend\n```\n\n#### no_doc\n\nIf you wish to make a request via the client that should not be included in your documentation, do it inside of a no_doc block.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      no_doc do\n        # Create an order via the API instead of via factories, don't document it\n        client.post \"/orders\", order_hash\n      end\n\n      do_request\n\n      expect(status).to eq 200\n    end\n  end\nend\n```\n\n#### params\n\nGet a hash of parameters that will be sent. See `parameter` documentation for an example.\n\n#### header\n\nThis method takes the header name and value.\n\n```ruby\nresource \"Orders\" do\n  before do\n    header \"Accept\", \"application/json\"\n  end\n\n  get \"/orders\" do\n    example_request \"Headers\" do\n      expect(headers).to eq { \"Accept\" =\u003e \"application/json\" }\n    end\n  end\nend\n```\n\n#### headers\n\nThis returns the headers that were sent as the request. See `header` documentation for an example.\n\n#### response_body\n\nReturns a string containing the response body from the previous request.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      do_request\n\n      expect(response_body).to eq [{ :name =\u003e \"Order 1\" }].to_json\n    end\n  end\nend\n```\n\n#### response_headers\n\nReturns a hash of the response headers from the previous request.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      do_request\n\n      expect(response_headers[\"Content-Type\"]).to eq \"application/json\"\n    end\n  end\nend\n```\n\n#### status, response_status\n\nReturns the numeric status code from the response, eg. 200. `response_status` is an alias to status because status is commonly a parameter.\n\n```ruby\nresource \"Order\" do\n  get \"/orders\" do\n    example \"Listing orders\" do\n      do_request\n\n      expect(status).to eq 200\n      expect(response_status).to eq 200\n    end\n  end\nend\n```\n\n#### query_string\n\nData that will be sent as a query string instead of post data. Used in GET requests.\n\n```ruby\nresource \"Orders\" do\n  parameter :name\n\n  let(:name) { \"My Order\" }\n\n  get \"/orders\" do\n    example \"List orders\" do\n      expect(query_string).to eq \"name=My+Orders\"\n    end\n  end\nend\n```\n\n#### raw_post\n\nYou can completely override what gets sent as parameters by `let`-ing `raw_post`.\n\n```ruby\nresource \"Orders\" do\n  header \"Content-Type\", \"application/json\"\n\n  parameter :name\n\n  let(:name) { \"My Order\" }\n\n  post \"/orders\" do\n    let(:raw_post) { params.to_json }\n\n    example_request \"Create new order\" do\n      # params get sent as JSON\n    end\n  end\nend\n```\n\n## Rake Task\n\nThe gem contains a Railtie that defines a rake task for generating docs easily with Rails.\nIt loads all files in `spec/acceptance/**/*_spec.rb`.\n\n```bash\n$ rake docs:generate\n```\n\nIf you are not using Rails, you can use Rake with the following Task:\n\n```ruby\nrequire 'rspec/core/rake_task'\n\ndesc 'Generate API request documentation from API specs'\nRSpec::Core::RakeTask.new('docs:generate') do |t|\n  t.pattern = 'spec/acceptance/**/*_spec.rb'\n  t.rspec_opts = [\"--format RspecApiDocumentation::ApiFormatter\"]\nend\n```\n\nor\n\n```ruby\nrequire 'rspec_api_documentation'\nload 'tasks/docs.rake'\n```\n\nIf you are not using Rake:\n\n```bash\n$ rspec spec/acceptance --format RspecApiDocumentation::ApiFormatter\n```\n\n## Uploading a file\n\nFor an example on uploading a file see `examples/spec/acceptance/upload_spec.rb`.\n\n## Gotchas\n\n- rspec_api_documentation relies on a variable `client` to be the test client. If you define your own `client` please configure rspec_api_documentation to use another one, see Configuration above.\n- We make heavy use of RSpec metadata, you can actually use the entire gem without the DSL if you hand write the metadata.\n- You must use `response_body`, `status`, `response_content_type`, etc. to access data from the last response. You will not be able to use `response.body` or `response.status` as the response object will not be created.\n","funding_links":[],"categories":["Documentation Tools","Ruby","Documentation","api"],"sub_categories":["Documentation Generators"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzipmark%2Frspec_api_documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzipmark%2Frspec_api_documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzipmark%2Frspec_api_documentation/lists"}