Define and serve live-updating Swagger JSON for Ruby apps.
Define and serve live-updating Swagger JSON for Ruby apps.
Swagger::Blocks is a DSL for pure Ruby code blocks that can be turned into JSON.
It helps you write API docs in the Swagger style in Ruby and then automatically build JSON that is compatible with Swagger UI.
Add this line to your application's Gemfile:
gem 'swagger-blocks'Or install directly with gem install swagger-blocks.
This is a simplified example based on the objects in the Petstore Swagger Sample App. For a more complex and complete example, see the swagger_v2_blocks_spec.rb file.
Also note that Rails is not required, you can use Swagger::Blocks in plain Ruby objects.
class PetsController = 2.0.0, but you may use [1.4.0](https://github.com/fotinakis/swagger-blocks/tree/v1.4.0).
## Contributing
1. Fork it ( https://github.com/fotinakis/swagger-blocks/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
Throw a ★ on it! :)
## Filing issues
**Please DO [file an issue](https://github.com/fotinakis/swagger-blocks/issues)**:
- If you find a bug or some part of the Swagger 2.0 spec that swagger-blocks does not support.
- To propose and discuss a code change before submitting a PR for it.
- To talk about anything related specifically to swagger-blocks, not Swagger itself.
**Please DO NOT file an issue**:
- If you have a question about Swagger or Swagger UI. We simply cannot support all Swagger-related questions. Check out the http://swagger.io/community/ for help.
## Release notes
* v2.0.1: Bugfix to allow nested arrays of `items`.
* v2.0.0: Code cleanup, drop support for Swagger 1.2 spec.
* v1.4.0: Allow parameters to be defined once in swagger_root and reused.
* v1.3.4: Fix support for fully-qualified URIs in `$ref` values.
* v1.3.3: Bugfix to allow `parameter` inside `swagger_path`.
* v1.3.2: Bugfix to allow `property` inside `items` for rare extended schema uses.
* v1.3.1: Bugfix to allow nested objects via `property` nested in `property`.
* v1.3.0: Added support for condensed syntax via inline keys on every block.
* v1.2.0: Improved support for `$ref` Path Item Object parameters.
* v1.1.3: Rename tags directive to tag for consistency.
* v1.1.2: Bugfix for security definition support.
* v1.1.1: Bugfix for tags node support.
* v1.1: Support for Swagger 2.0 spec.
* v1.0.1: Make backwards-compatible with Ruby 1.9.3.
* v1.0.0: Initial major release.
## Credits
Thanks to [@ali-graham](https://github.com/ali-graham) for contributing support for Swagger 2.0.
Original idea inspired by [@richhollis](https://github.com/richhollis/)'s [swagger-docs](https://github.com/richhollis/swagger-docs/) gem.No open issues yet, or sync has not completed.