{"id":15403863,"url":"https://github.com/twe4ked/rspec-api-docs","last_synced_at":"2026-04-18T07:36:37.788Z","repository":{"id":66271123,"uuid":"76708252","full_name":"twe4ked/rspec-api-docs","owner":"twe4ked","description":"Generate API documentation using RSpec","archived":false,"fork":false,"pushed_at":"2018-11-01T22:16:50.000Z","size":167,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T01:52:04.395Z","etag":null,"topics":["api","documentation","dsl","formatter","rspec"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/rspec-api-docs","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twe4ked.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2016-12-17T06:34:44.000Z","updated_at":"2022-08-27T06:47:19.000Z","dependencies_parsed_at":"2023-03-13T20:30:13.523Z","dependency_job_id":null,"html_url":"https://github.com/twe4ked/rspec-api-docs","commit_stats":{"total_commits":154,"total_committers":5,"mean_commits":30.8,"dds":"0.058441558441558406","last_synced_commit":"b9f5b3a0db44d2b047f33f0794f6b8f1bd1c08ed"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/twe4ked/rspec-api-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twe4ked%2Frspec-api-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twe4ked%2Frspec-api-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twe4ked%2Frspec-api-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twe4ked%2Frspec-api-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twe4ked","download_url":"https://codeload.github.com/twe4ked/rspec-api-docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twe4ked%2Frspec-api-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267678448,"owners_count":24126333,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","documentation","dsl","formatter","rspec"],"created_at":"2024-10-01T16:10:25.735Z","updated_at":"2026-04-18T07:36:32.765Z","avatar_url":"https://github.com/twe4ked.png","language":"Ruby","readme":"\u003ch1 align=\"center\"\u003erspec-api-docs\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eGenerate API documentation using RSpec\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/twe4ked/rspec-api-docs\"\u003e\u003cimg src=\"https://img.shields.io/travis/twe4ked/rspec-api-docs.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://rubygems.org/gems/rspec-api-docs\"\u003e\u003cimg src=\"https://img.shields.io/gem/v/rspec-api-docs.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"http://www.rubydoc.info/github/twe4ked/rspec-api-docs/master\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-master-lightgrey.svg?style=flat-square\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**rspec-api-docs** provides a way to generate documentation from your request\nspecs. It does this by providing a simple DSL and a custom formatter.\n\nThe default renderer produces a [single JSON file] which can be used by\n[api-docs] to [display your documentation].\n\n[single JSON file]: ./spec/integration/output/json/index.json\n[display your documentation]: https://twe4ked.github.io/api-docs/\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'rspec-api-docs'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install rspec-api-docs\n\n## Usage\n\n**rspec-api-docs** works in two stages. The first stage introduces a new DSL\nmethod, `doc`, to include in your RSpec specs.\n\n``` ruby\nrequire 'rspec_api_docs/dsl'\n\nRSpec.describe 'Characters' do\n  include RspecApiDocs::Dsl\n\n  # ...\nend\n```\n\nThe `doc` method stores data in a hash on the RSpec example metadata.\n\nThe second stage is the formatter (`RspecApiDocs::Formatter`). The formatter\nparses the hash stored on each RSpec example and uses a\n[renderer](lib/rspec_api_docs/formatter/renderer/README.md) to write out your\ndocumentation.\n\n```\n$ rspec spec/requests/characters_spec.rb --formatter=RspecApiDocs::Formatter\n```\n\n### DSL\n\nFirst, require the DSL and include the DSL module.\n\nYou can do this in your `spec_helper.rb`:\n\n``` ruby\nrequire 'rspec_api_docs/dsl'\n\nRSpec.configure do |config|\n  config.include RspecApiDocs::Dsl, type: :request\n\n  # ...\nend\n```\n\nOr in individual specs:\n\n\n``` ruby\nrequire 'rspec_api_docs/dsl'\n\nRSpec.describe 'Characters' do\n  include RspecApiDocs::Dsl\n\n  # ...\nend\n```\n\nYou also need to require a lambda that runs after each expectation:\n\n``` ruby\nrequire 'rspec_api_docs/after'\n\nRSpec.configure do |config|\n  config.after \u0026RspecApiDocs::After::Hook\nend\n```\n\nThis automatically stores the `last_request` and `last_response` objects for\nuse by the formatter.\n\n**rspec-api-docs** doesn't touch any of the built-in RSpec DSL methods.\nEverything is contained in the `doc` block.\n\nYou can use RSpec `before` blocks to share setup between multiple examples.\n\n``` ruby\nrequire 'rspec_api_docs/dsl'\n\nRSpec.describe 'Characters' do\n  include RspecApiDocs::Dsl\n\n  before do\n    doc do\n      resource_name 'Characters'\n      resource_description \u003c\u003c-EOF\n        Characters inhabit the Land of Ooo.\n      EOF\n    end\n  end\n\n  describe 'GET /characters/:id' do\n    it 'returns a character' do\n      doc do\n        name 'Fetching a Character'\n        description 'For getting information about a Character.'\n        path '/characters/:id'\n\n        field :id, 'The id of a character', scope: :character, type: 'integer'\n        field :name, \"The character's name\", scope: :character, type: 'string'\n      end\n\n      get '/characters/1'\n\n      # normal expectations ...\n    end\n\n    # ...\n  end\nend\n```\n\n#### `resource_name`\n\nAccepts a string of the name of the resource.\n\n\u003e Characters\n\n#### `resource_description`\n\nAccepts a string that describes the resource.\n\n\u003e Characters inhabit the Land of Ooo.\n\n#### `resource_precedence`\n\nAccepts an optional integer.\n\nLower numbers are ordered first.\n\n#### `name`\n\nAccepts a string of the name of the resource.\n\n\u003e Fetching a character\n\nNote: This defaults to the \"description\" of the RSpec example.\n\n\n``` ruby\nit 'Fetching a character' do\n  # ...\nend\n```\n\n#### `description`\n\nAccepts a string that describes the example.\n\n\u003e To find out information about a Character.\n\n#### `path`\n\nAccepts a string for the path requested in the example.\n\n\u003e /characters/:id\n\nNote: This defaults to the path of the first route requested in the example.\n\n#### `field`\n\nAccepts a `name`, `description`, and optionally a `scope`, `type`, and `example`.\n\n- `name` [`Symbol`] the name of the response field\n- `description` [`String`] a description of the response field\n- `scope` [`Symbol`, `Array\u003cSymbol\u003e`] _(optional)_ how the field is scoped\n- `type` [`String`] _(optional)_ the type of the returned field\n- `example` _(optional)_ an example value\n\nThis can be called multiple times for each response field.\n\n``` ruby\nfield :id, 'The id of a character', scope: :character, type: 'integer', example: 42\nfield :name, \"The character's name\", scope: :character, type: 'string'\n```\n\nThe `example` is useful if the data might change (i.e. a database ID column).\nThe value will be substituted in the resulting JSON.\n\n#### `param`\n\nAccepts a `name`, `description`, and optionally a `scope`, `type`, and `required` flag.\n\n- `name` [`Symbol`] the name of the parameter\n- `description` [`Symbol`] a description of the parameter\n- `scope` [`Symbol`, `Array\u003cSymbol\u003e`] _(optional)_ how the parameter is scoped\n- `type` [`String`] _(optional)_ the type of the parameter\n- `required` [`Boolean`] _(optional)_ if the parameter is required\n\nThis can be called multiple times for each parameter.\n\n``` ruby\nparam :id, 'The id of a character', scope: :character, type: 'integer', required: true\nparam :name, \"The character's name\", scope: :character, type: 'string'\n```\n\n#### `note`\n\nAccepts a `note` and optional `level`.\n\n- `level` [`Symbol`] one of `:success`, `:info`, `:warning`, or `:danger`. Defaults to `:info`\n- `note` [`String`] the note\n\n``` ruby\nnote 'You need to supply an id!'\nnote :warning, \"An error will be thrown if you don't supply an id!\"\n```\n\n#### `precedence`\n\nAccepts an optional integer.\n\nLower numbers are ordered first.\n\nSee the integration specs for more examples of the DSL in use.\n\n### Formatter\n\nThe formatter can be configured in your `spec_helper.rb`:\n\n``` ruby\n# Defaults are shown\n\nRspecApiDocs.configure do |config|\n  # The output directory for file(s) created by the renderer.\n  config.output_dir = 'docs'\n\n  # One of :json, :raddocs, or :slate.\n  # This can also be a class that quacks like a renderer.\n  # A renderer is initialized with an array of `Resource`s and a `#render`\n  # method is called.\n  config.renderer = :json\n\n  # Set to false if you don't want to validate params are documented and their\n  # types in the after block.\n  config.validate_params = true\nend\n```\n\nSee [the documentation](http://www.rubydoc.info/github/twe4ked/rspec-api-docs/master).\n\n## Rake tasks\n\n``` ruby\nrequire 'rspec_api_docs/rake_task'\n\nRspecApiDocs::Rake.new do |task| # docs:generate\n  # Pattern for where to find the specs\n  task.pattern = 'spec/requests/**/*_spec.rb'\n\n  # Extra RSpec options\n  task.rspec_opts = ['--format progress']\nend\n\nRspecApiDocs::Rake.new do |task| # docs:ensure_updated\n  # Same as options above with some extras for when verify is true\n\n  # Raise an error if the generated docs don't match the existing docs\n  # The verify option only works with the :json renderer.\n  task.verify = true\n\n  # The existing (committed) output file\n  task.existing_file = 'docs/index.json'\nend\n\n# Non-verify task with custom name\nRspecApiDocs::Rake.new :custom_task_name\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake` to run the tests.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and tags, and push the `.gem` file to [rubygems.org].\n\nRegenerate this project's integration spec docs locally:\n\n```\n$ ./bin/generate_integration_docs\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/twe4ked/rspec-api-docs. This project is intended to be a\nsafe, welcoming space for collaboration, and contributors are expected to\nadhere to the [Contributor Covenant] code of\nconduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License].\n\n[MIT License]: http://opensource.org/licenses/MIT\n[Contributor Covenant]: http://contributor-covenant.org\n[rubygems.org]: https://rubygems.org\n[api-docs]: https://github.com/twe4ked/api-docs\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwe4ked%2Frspec-api-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwe4ked%2Frspec-api-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwe4ked%2Frspec-api-docs/lists"}