mirror of
https://github.com/ditkrg/rswag.git
synced 2026-01-23 06:16:42 +00:00
Update changelog and tweak readme
This commit is contained in:
Greg Myers
parent
2d5da62bf1
commit
4516ad4b78
12
CHANGELOG.md
12
CHANGELOG.md
@ -6,14 +6,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
### Added
|
||||
- New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251)
|
||||
### Changed
|
||||
- rswag-api will serve yaml files as yaml [#251](https://github.com/rswag/rswag/pull/251)
|
||||
### Deprecated
|
||||
### Removed
|
||||
### Fixed
|
||||
### Security
|
||||
|
||||
## [2.2.0] - 2019-11-01
|
||||
### Added
|
||||
- New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251)
|
||||
### Changed
|
||||
- rswag-api will serve yaml files as yaml [#251](https://github.com/rswag/rswag/pull/251)
|
||||
|
||||
## [2.1.1] - 2019-10-18
|
||||
### Fixed
|
||||
- Fix incorrect require reference for swagger_generator [#248](https://github.com/rswag/rswag/issues/248)
|
||||
|
||||
## [2.1.0] - 2019-10-17
|
||||
### Added
|
||||
- New Spec Generator [#75](https://github.com/rswag/rswag/pull/75)
|
||||
|
||||
26
README.md
26
README.md
@ -5,7 +5,7 @@ rswag
|
||||
|
||||
[Swagger](http://swagger.io) tooling for Rails API's. Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests.
|
||||
|
||||
Rswag extends rspec-rails "request specs" with a Swagger-based DSL for describing and testing API operations. You describe your API operations with a succinct, intuitive syntax, and it automaticaly runs the tests. Once you have green tests, run a rake task to auto-generate corresponding Swagger files and expose them as JSON endpoints. Rswag also provides an embedded version of the awesome [swagger-ui](https://github.com/swagger-api/swagger-ui) that's powered by the exposed JSON. This toolchain makes it seamless to go from integration specs, which youre probably doing in some form already, to living documentation for your API consumers.
|
||||
Rswag extends rspec-rails "request specs" with a Swagger-based DSL for describing and testing API operations. You describe your API operations with a succinct, intuitive syntax, and it automaticaly runs the tests. Once you have green tests, run a rake task to auto-generate corresponding Swagger files and expose them as YAML or JSON endpoints. Rswag also provides an embedded version of the awesome [swagger-ui](https://github.com/swagger-api/swagger-ui) that's powered by the exposed file. This toolchain makes it seamless to go from integration specs, which youre probably doing in some form already, to living documentation for your API consumers.
|
||||
|
||||
And that's not all ...
|
||||
|
||||
@ -16,7 +16,7 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
|
||||
|Rswag Version|Swagger (OpenAPI) Spec.|swagger-ui|
|
||||
|----------|----------|----------|
|
||||
|[master](https://github.com/rswag/rswag/tree/master)|2.0|3.18.2|
|
||||
|[2.1.1](https://github.com/rswag/rswag/tree/2.1.1)|2.0|3.18.2|
|
||||
|[2.2.0](https://github.com/rswag/rswag/tree/2.2.0)|2.0|3.18.2|
|
||||
|[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5|
|
||||
|
||||
## Getting Started ##
|
||||
@ -123,6 +123,9 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
|
||||
end
|
||||
```
|
||||
|
||||
There is also a generator which can help get you started `rails generate rspec:swagger API::MyController`
|
||||
|
||||
|
||||
4. Generate the Swagger JSON file(s)
|
||||
|
||||
```ruby
|
||||
@ -190,7 +193,7 @@ describe 'Blogs API' do
|
||||
end
|
||||
end
|
||||
```
|
||||
*Note:* the OAI v3 may be released soon(ish?) and include a nullable property. This may have an effect on the need/use of custom extension to the draft. Do not use this property if you don't understand the implications.
|
||||
*Note:* OAI v3 has a nullable property. Rswag will work to support this soon. This may have an effect on the need/use of custom extension to the draft. Do not use this property if you don't understand the implications.
|
||||
<https://github.com/OAI/OpenAPI-Specification/issues/229#issuecomment-280376087>
|
||||
|
||||
### Global Metadata ###
|
||||
@ -213,8 +216,8 @@ RSpec.configure do |config|
|
||||
basePath: '/api/v1'
|
||||
},
|
||||
|
||||
'v2/swagger.json' => {
|
||||
swagger: '2.0',
|
||||
'v2/swagger.yaml' => {
|
||||
openapi: '3.0.0',
|
||||
info: {
|
||||
title: 'API V2',
|
||||
version: 'v2',
|
||||
@ -231,7 +234,7 @@ By default, the paths, operations and responses defined in your spec files will
|
||||
|
||||
```ruby
|
||||
# spec/integration/v2/blogs_spec.rb
|
||||
describe 'Blogs API', swagger_doc: 'v2/swagger.json' do
|
||||
describe 'Blogs API', swagger_doc: 'v2/swagger.yaml' do
|
||||
|
||||
path '/blogs' do
|
||||
...
|
||||
@ -448,6 +451,17 @@ RSpec.configure do |config|
|
||||
config.swagger_dry_run = false
|
||||
end
|
||||
```
|
||||
|
||||
### Running tests without documenting ###
|
||||
|
||||
If you want to use Rswag for testing without adding it to you swagger docs, you can simply nullify the response metadata after the test run.
|
||||
|
||||
```ruby
|
||||
after do |example|
|
||||
example.metadata[:response] = null
|
||||
end
|
||||
```
|
||||
|
||||
### Route Prefix for Swagger JSON Endpoints ###
|
||||
|
||||
The functionality to expose Swagger files, such as those generated by rswag-specs, as JSON endpoints is implemented as a Rails Engine. As with any Engine, you can change it's mount prefix in _routes.rb_:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user