# grape-swagger: OpenAPI documentation generated from a Grape API > grape-swagger reads a Grape application and produces a Swagger-compliant description of it, so an API defined in Ruby gets a browsable specification without a second source of truth. The cost is version coupling, and the compatibility table in the README is the document that governs whether your grape and grape-entity versions will work at all. **ruby-grape/grape-swagger** — Add OAPI/swagger v2.0 compliant documentation to your grape API - Repository: https://github.com/ruby-grape/grape-swagger - Stars: 1,102 · Forks: 477 - Language: Ruby - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/ruby-grape-grape-swagger ## One declaration of the API, two artefacts from it grape-swagger provides autogenerated documentation for a Grape API, and the generated documentation is Swagger-compliant, meaning it can easily be discovered in Swagger UI. The point of the design is that there is a single declaration of the API. In Grape, the routes, their parameters, their descriptions and their entity classes already exist in Ruby, so a separate hand-written specification file is a second source of truth that drifts. The README says you should be able to point the petstore demo at your API, which is the quickest way to see whether your routes come out as you expect, and the screenshot in the README is based on the Hussars sample app. The gem sits in the ruby-grape organisation next to Grape Swagger Entity and Grape Swagger Representable, so the wider toolchain around it is the same family of adapters that turn Ruby objects into described data. ## The compatibility table is the document that matters Before anything else, the README states that the following versions of grape, grape-entity and grape-swagger can currently be used together, and then gives a table. The rows show how tightly coupled the pieces are. grape-swagger 0.10.5 and 0.11.0 produce swagger spec 1.2 documents, working with grape from 0.10.0 up to 0.14.0 in the first case and 0.16.2 and above in the second, with grape-entity below 0.5.0 and representable marked not applicable. From grape-swagger 0.25.2 onwards the generated documents are swagger spec 2.0, the grape range moves to 0.16.2 and above up to 1.1.0 for the later rows, and grape-entity moves to 0.5.0 and above with representable at 2.4.1 and above. That is a wide spread of moving parts for a documentation gem, and it is the first thing to check before anything else, because a mismatched pair produces a document that is wrong rather than an error that is obvious. ## Configuration: base paths, versions and who may see the docs The configuration section is long, and its shape tells you what the gem has to solve. There are the path and host options, with host, base_path, mount_path, add_base_path, add_root and add_version controlling where the generated document claims the API lives, and doc_version controlling the version of the document itself. Then there is the security group, with endpoint_auth_wrapper and swagger_endpoint_guard, which are hooks for your own authentication, token_owner, security_definitions and security for describing the scheme itself, and hide_documentation_path, which defaults to true, meaning the route that serves the documentation is not advertised unless you say otherwise. That default is the right one for a public API and the wrong one for an internal one, so it is worth knowing it exists. The rest of the options cover the document's own metadata and shape, with info, models, tags, array_use_braces, api_documentation and specific_api_documentation, and consumes and produces for the media types. The per-endpoint variants of api_documentation let one route be documented differently from the rest, which is how a single unusual endpoint avoids polluting a global setting. ## Route-level overrides, including hiding and deprecating The routes configuration section is the longest part of the README and it is where most of the day-to-day work happens. The documentation describes a long series of overrides, and the list reads like a list of the things you will actually need. You can add swagger header parameters, hide an endpoint from the document, override the auto-generated nicknames that otherwise come from the route path, specify endpoint details, override the route summary, override the tags, and mark a route as deprecated. There are overrides for the name of the body parameter, for defining an endpoint as an array, for using an options hash, for the parameter type and the data type of the parameter, for declaring multiple types, for an array of a given data type, and for the collection format of arrays. You can hide parameters, set a Swagger default value, and control additionalProperties for object-type parameters in three ways, allowing any additional properties, allowing any additional properties of a particular type, or allowing additional properties that match a defined schema, along with setting an example parameter value. The pattern is consistent throughout, which is a real strength of the project even if the list of knobs is long. ## Grape Entities, relationships and inheritance in the schema The Grape Entities section covers the data side of the document, and it is where a schema stops being a list of strings. There is a documented class or definition for a documented entity, a way to give a model a custom description and example, and a section on relationships, split into the one-to-many case, the one-to-one case, and inheritance expressed with allOf and a discriminator. Inheritance with a discriminator is the piece that matters for larger schemas, because it is how a consumer of the generated document knows which of several similar shapes a field actually is. The example directory in the repository holds a runnable API, a config.ru, a Postman collection of example requests and the two images the README embeds, so the practical reference for all of this is a working sample rather than a snippet. ## Rake tasks, validation and locking down the UI The Rake tasks section is the one that turns the gem into part of a build pipeline, and it lists two entries, one for OpenApi and Swagger documentation and one for OpenApi and Swagger validation. The second is the interesting one for a team, because a generator that produces a document nobody checks will drift from the API, and a validation task is what makes the document part of continuous integration rather than a snapshot. There is also a section on securing the Swagger UI, which is a real concern given that a generated document tells an outsider exactly which endpoints you have and what they expect, and hide_documentation_path only stops the route being advertised rather than stopping anyone who knows the path. The rest of the repository is the standard Ruby gem layout, with lib/, spec/, a gemspec, a Rakefile, .rspec, rubocop configuration split into .rubocop.yml and .rubocop_todo.yml, a Dangerfile for pull request checks, and CHANGELOG.md, UPGRADING.md and RELEASING.md for the release process. The last push was on 2026-10-14, and the project publishes no GitHub releases, so the changelog and the rubygems version are what you track. ## Conclusion Adopt grape-swagger if you already build your API with Grape and want a Swagger 2.0 document generated from the same declarations, with the option to override details per route and to validate it in CI. Do not adopt it if your API is not written in Grape, or if you need OpenAPI 3, since the versions listed in the compatibility table produce swagger spec 2.0 documents. Before you pin a version, check the compatibility table for your grape, grape-entity and representable versions, and read UPGRADING.md, since the option set has changed across releases. ## FAQ ### What is grape-swagger? It is a Ruby gem that provides autogenerated Swagger-compliant documentation for a Grape API, so the same route declarations produce both the service and a browsable specification in Swagger UI. It is MIT licensed and maintained in the ruby-grape organisation. ### Which versions of grape and grape-entity work with grape-swagger? The README gives a compatibility table. The rows for grape-swagger 0.25.2 and later produce swagger spec 2.0 documents, work with grape from 0.16.2 up to 1.1.0 and grape-entity from 0.5.0, with representable at 2.4.1 and above, while the 0.10.5 and 0.11.0 rows produce spec 1.2 documents. ### Does grape-swagger hide the documentation endpoint by default? Yes. The configuration option hide_documentation_path defaults to true, so the route serving the documentation is not advertised unless you change it. The options swagger_endpoint_guard and endpoint_auth_wrapper are there to control who can reach it. ### Can I override the documentation for a single endpoint? Yes. There are per-endpoint overrides for the summary, the tags, the parameter types and data types, the body parameter name, the nickname, the status codes, the response examples and headers, and there is a specific_api_documentation configuration for documenting one route differently from the rest. ### How do I check the generated document in CI? The Rake tasks section lists a documentation task and a validation task for OpenApi and Swagger, and the repository also carries a Rakefile, a Dangerfile for pull request checks and a Postman collection of example requests in the example directory. The last push was on 2026-10-14. ## Sources - [Issues](https://github.com/ruby-grape/grape-swagger/issues) - [License: MIT](https://github.com/ruby-grape/grape-swagger/blob/master/LICENSE) - [README](https://github.com/ruby-grape/grape-swagger/blob/master/README.md) - [ruby-grape/grape-swagger on GitHub](https://github.com/ruby-grape/grape-swagger) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ruby-grape-grape-swagger