{"id":13878524,"url":"https://github.com/drewish/rspec-rails-swagger","last_synced_at":"2025-04-07T16:18:43.806Z","repository":{"id":11312089,"uuid":"68214155","full_name":"drewish/rspec-rails-swagger","owner":"drewish","description":"Generate Swagger 2.0 docs for Rails apps using RSpec request specs. Test results can be captured as response examples.","archived":false,"fork":false,"pushed_at":"2022-05-27T02:26:45.000Z","size":115,"stargazers_count":84,"open_issues_count":13,"forks_count":22,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T14:12:51.961Z","etag":null,"topics":["rails","rspec","swagger"],"latest_commit_sha":null,"homepage":"","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/drewish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2016-09-14T14:37:49.000Z","updated_at":"2024-12-30T15:38:30.000Z","dependencies_parsed_at":"2022-08-20T16:10:37.022Z","dependency_job_id":null,"html_url":"https://github.com/drewish/rspec-rails-swagger","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewish%2Frspec-rails-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewish%2Frspec-rails-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewish%2Frspec-rails-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewish%2Frspec-rails-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drewish","download_url":"https://codeload.github.com/drewish/rspec-rails-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247685628,"owners_count":20979085,"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":["rails","rspec","swagger"],"created_at":"2024-08-06T08:01:52.098Z","updated_at":"2025-04-07T16:18:43.787Z","avatar_url":"https://github.com/drewish.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# RSpec Rails Swagger\n\n[![Build Status](https://travis-ci.org/drewish/rspec-rails-swagger.svg?branch=master)](https://travis-ci.org/drewish/rspec-rails-swagger)\n[![Code Climate](https://codeclimate.com/github/drewish/rspec-rails-swagger/badges/gpa.svg)](https://codeclimate.com/github/drewish/rspec-rails-swagger)\n\nThis gem helps you generate Swagger docs by using RSpec to document the paths.\nYou execute a command to run the tests and generate the `.yaml` or `.json` output.\nRunning the tests ensures that your API and docs are in agreement, and generates\noutput that can be saved as response examples.\n\nThe design of this was heavily influenced by the awesome [swagger_rails gem](https://github.com/domaindrivendev/swagger_rails).\n\n## Setup\n\nAdd the gem to your Rails app's `Gemfile`:\n```rb\ngroup :development, :test do\n  gem 'rspec-rails-swagger'\nend\n```\n\nUpdate your bundle:\n```\nbundle install\n```\n\nIf you don't have a `spec/rails_helper.rb` file:\n```\nrails generate rspec:install\n```\n\nCreate the `spec/swagger_helper.rb` file:\n```\nrails generate rspec:swagger_install\n```\n\n## Documenting Your API\n\nNow you can edit `spec/swagger_helper.rb` and start filling in the top level\nSwagger documentation, e.g. basePath, [definitions](http://swagger.io/specification/#definitionsObject),\n[parameters](http://swagger.io/specification/#parametersDefinitionsObject),\n[tags](http://swagger.io/specification/#tagObject), etc.\n\nYou can use the generator to create a spec to documentation a controller:\n\n```\nrails generate rspec:swagger PostsController\n```\n\nThat will create a `spec/requests/posts_spec.rb` file with the paths, operations\nand some default requests filled in. With the structure in place you should only\nneed to add `before` calls to create records and then update the `let`s to\nreturn the appropriate values.\n\n## Generate the JSON or YAML\n\nTo create the Swagger files use the rake task:\n\n```\nbundle exec rake swagger\n```\n\nNow you can use Swagger UI or the renderer of your choice to display the\nformatted documentation. [swagger_engine](https://github.com/batdevis/swagger_engine)\nworks pretty well and supports multiple documents.\n\n## RSpec DSL\n\nThe DSL follows the hierarchy of the Swagger Schema:\n\n- [Paths Object](http://swagger.io/specification/#paths-object-29)\n  - [Path Item Object](http://swagger.io/specification/#path-item-object-32)\n    - [Parameter Object](http://swagger.io/specification/#parameter-object-44)s (Optional)\n    - [Operation Object](http://swagger.io/specification/#operation-object-36)\n      - [Parameter Object](http://swagger.io/specification/#parameter-object-44)s (Optional)\n      - [Responses Object](http://swagger.io/specification/#responses-object-54)\n        - [Response Object](http://swagger.io/specification/#response-object-58)\n          - [Example Object](http://swagger.io/specification/#example-object-65)s (Optional)\n\nHere's an example of a spec with comments to for the corresponding objects:\n\n```rb\nrequire 'swagger_helper'\n\n# Paths Object\nRSpec.describe \"Posts Controller\", type: :request do\n  before { Post.new.save }\n\n  # Path Item Object\n  path '/posts' do\n    # Operation Object\n    operation \"GET\", summary: \"fetch list\" do\n      # Response Object\n      response 200, description: \"successful\"\n    end\n  end\n\n  # Path Object\n  path '/posts/{post_id}' do\n    # Parameter Object\n    parameter \"post_id\", { in: :path, type: :integer }\n    let(:post_id) { 1 }\n\n    # Operation Object\n    get summary: \"fetch item\" do\n      # Response Object\n      response 200, description: \"success\"\n    end\n  end\n\n  # Path Post Object\n  path '/posts/' do\n    # Parameter Object for content type could be defined like:\n    consumes 'application/json'\n    # or:\n    parameter 'Content-Type', { in: :header, type: :string }\n    let(:'Content-Type') { 'application/json' }\n    # one of them would be considered\n\n    # authorization token in the header:\n    parameter 'Authorization', { in: :header, type: :string }\n    let(:'Authorization') { 'Bearer \u003ctoken-here\u003e' }\n\n    # Parameter Object\n    parameter \"post_id\", { in: :path, type: :integer }\n    let(:post_id) { 1 }\n\n    # Parameter Object for Body\n    parameter \"body\", { in: :body, required: true, schema: {\n      type: :object,\n        properties: {\n          title: { type: :string },\n          author_email: { type: :email }\n        }\n    }\n    let (:body) {\n      { post:\n        { title: 'my example',\n          author_email: 'me@example.com' }\n        }\n      }\n    }\n\t# checkout http://swagger.io/specification/#parameter-object-44 for more information, options and details\n\n    # Operation Object\n    post summary: \"update an item\" do\n      # Response Object\n      response 200, description: \"success\"\n    end\n    # ...\nend\n```\n\n\n### Paths Object\nThese methods are available inside of an RSpec contexts with the `type: :request` tag.\n\n#### `path(template, attributes = {}, \u0026block)`\nDefines a new Path Item.\n\nThe `attributes` parameter accepts:\n- `swagger_doc` a key in `RSpec.configuration.swagger_docs` that determines\n  which file the path belongs in.\n- `tags` with an array of tags that will be applied to the child Operations.\n\nYou can also provide a default file and tags by setting them on a parent RSpec\ncontext block:\n```rb\nRSpec.describe \"Sample Requests\", type: :request do\n  # The swagger_doc will be used as a default for the paths defined within the\n  # context block. Similarly, the tags will be merged with those set on paths\n  # defined within them.\n  context \"setting defaults\", swagger_doc: 'default_document.json', tags: [:context_tag] do\n    path '/posts', swagger_doc: 'overridden_document.yaml' tags: ['path_tag'] do\n      operation \"GET\", summary: \"fetch list\" do\n        produces 'application/json'\n        tags 'operation_tag'\n\n        response(200, { description: \"successful\" })\n      end\n    end\n  end\nend\n```\nThe `GET /posts` operation in this example will be saved in the `'overridden_document.yaml'`\nfile and tagged with `[\"context_tag\", \"path_tag\", \"operation_tag\"]`.\n\n\n### Path Item Object\nThese methods are available inside of blocks passed to the `path` method.\n\n#### `operation(method, attributes = {}, \u0026block)`\nDefines a new Operation Object. The `method` is case insensitive.\n\nThe `attributes` parameter accepts:\n- `tags` with an array of tags. These will be merged with tags passed to the\n  Path Item or `tags` method inside the Operation's block.\n\n#### `delete(attributes = {}, \u0026block)`\nAlias for `operation(:delete, attributes, block)`.\n\n#### `get(attributes = {}, \u0026block)`\nAlias for `operation(:get, attributes, block)`.\n\n#### `head(attributes = {}, \u0026block)`\nAlias for `operation(:head, attributes, block)`.\n\n#### `options(attributes = {}, \u0026block)`\nAlias for `operation(:options, attributes, block)`.\n\n#### `patch(attributes = {}, \u0026block)`\nAlias for `operation(:patch, attributes, block)`.\n\n#### `post(attributes = {}, \u0026block)`\nAlias for `operation(:post, attributes, block)`.\n\n#### `put(attributes = {}, \u0026block)`\nAlias for `operation(:put, attributes, block)`.\n\n\n### Parameters\nThese methods are available inside of blocks passed to the `path` or `operation` method.\n\n#### `parameter(name, attributes = {})`\nDefines a new Parameter Object. You can define the parameter inline:\n```rb\nparameter :callback_url, in: :query, type: :string, required: true\n```\n\nOr, via reference:\n```rb\nparameter ref: \"#/parameters/site_id\"\n```\n\nValues for the parameters are set using `let`:\n```rb\npost summary: \"create\" do\n  parameter \"body\", in: :body, schema: { foo: :bar }\n  let(:body) { { post: { title: 'asdf', body: \"blah\" } } }\n  # ...\nend\n```\n\n\n### Operation Object\nThese methods are available inside of blocks passed to the `operation` method.\n\n#### `consumes(*mime_types)`\nUse this to add MIME types that are specific to the operation. They will be merged\nwith the Swagger Object's consumes field.\n```rb\nconsumes 'application/json', 'application/xml'\n```\n\n#### `produces(*mime_types)`\nUse this to add MIME types that are specific to the operation. They will be merged\nwith the Swagger Object's consumes field.\n```rb\nproduces 'application/json', 'application/xml'\n```\n\n#### `response(status_code, attributes = {}, \u0026block)`\nDefines a new Response Object. `status_code` must be between 1 and 599. `attributes`\nmust include a `description`.\n\n#### `tags(*tags)`\nAdds operation specific tags.\n```rb\ntags :accounts, :pets\n```\n\nYou can also provide tags through the RSpec context block and/or `path` method:\n```rb\nRSpec.describe \"Sample Requests\", type: :request, tags: [:context_tag] do\n  path '/posts', tags: ['path_tag'] do\n    operation \"GET\", summary: \"fetch list\" do\n      produces 'application/json'\n      tags 'operation_tag'\n\n      response(200, { description: \"successful\" })\n    end\n  end\nend\n```\nThese tags will be merged with those of the operation. The `GET /posts` operation\nin this example will be tagged with `[\"context_tag\", \"path_tag\", \"operation_tag\"]`.\n\n\n### Response Object\nThese methods are available inside of blocks passed to the `response` method.\n\n#### `capture_example()`\nThis method will capture the response body from the test and create an Example\nObject for the Response.\n\nYou could also set this in an RSpec context block if you'd like examples for\nmultiple operations or paths:\n```rb\ndescribe 'Connections', type: :request, capture_examples: true do\n  # Any requests in this block will capture example responses\nend\n```\n\n#### `schema(definition)`\nSets the schema field for the Response Object. You can define it inline:\n```rb\nschema(\n  type: :array,\n  items: {\n    type: :object,\n    properties: {\n      id: { type: :string },\n      name: { type: :string },\n    },\n  }\n)\n```\n\nOr, by reference:\n```rb\nschema ref: '#/definitions/Account'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewish%2Frspec-rails-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrewish%2Frspec-rails-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewish%2Frspec-rails-swagger/lists"}