Generate a valid and up to date swagger documentation out of your dry-structs and dry-validations
The gem is still work in progress and is not yet fully tested.
If you are upgrading from version 1 to version 2, you will need to replace:
Dry::Swagger::StructParser.new.call(struct)
with
Dry::Swagger::DocumentationGenerator.new.from_struct(struct)
and replace
Dry::Swagger::ContractParser.new.call(contract)
with
Dry::Swagger::DocumentationGenerator.new.from_validation(contract).
For the configuration file in project/config/initializers/dry-swagger.rb, you will need to replace:
Dry::Swagger::Config::ContractConfiguration -> Dry::Swagger::Config::SwaggerConfiguration
you do not need both ContractConfiguration and StructConfiguration.
Add this line to your application's Gemfile:
gem 'dry-swagger'
And then execute:
bundle install
After installing, execute the following command:
rake dry-swagger:install
This will generate configuration files in your project under project/config
. See Configuration section for more details.
class TestContract < Dry::Validation::Contract
params do
required(:some_field).value(:str?, min_size?: 5, max_size?: 10)
required(:some_array_of_objects).array(:hash) do
required(:some_nested_attribute).value(:str?)
end
required(:some_array_of_integers).array(:int?)
required(:dto).value(:hash) do
optional(:some_nested_attribute).maybe(:str?)
end
end
end
Dry::Swagger::DocumentationGenerator.new.from_validation(TestContract)
=> {
"type": "object",
"properties": {
"some_field": {
"type": "string",
"description": "Minimum size: 5, Maximum size: 10",
"x-nullable": false
},
"some_array_of_objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"some_nested_attribute": {
"type": "string",
"x-nullable": false
}
},
"required": [
"some_nested_attribute"
],
"x-nullable": false
},
"x-nullable": false
},
"some_array_of_integers": {
"type": "array",
"items": {
"type": "integer",
"x-nullable": false
},
"x-nullable": false
},
"dto": {
"type": "object",
"properties": {
"some_nested_attribute": {
"type": "string",
"x-nullable": true
}
},
"required": [
],
"x-nullable": false
}
},
"required": [
"some_field",
"some_array_of_objects",
"some_array_of_integers",
"dto"
]
}
class DTO1 < Dry::Struct
attribute :dto1_field, Types::String
end
class DTO2 < Dry::Struct
attribute :dto2_field, Types::String
end
class DTO < Dry::Struct
attribute :dynamic_dto, DTO1 | DTO2
end
Dry::Swagger::DocumentationGenerator.new.from_struct(DTO)
=> {
"type": "object",
"properties": {
"dynamic_dto": {
"type": "object",
"properties": {
"definition_1": {
"type": "object",
"properties": {
"dto1_field": {
"type": "string",
"x-nullable": false
}
},
"required": [
"dto1_field"
],
"x-nullable": false
},
"definition_2": {
"type": "object",
"properties": {
"dto2_field": {
"type": "string",
"x-nullable": false
}
},
"required": [
"dto2_field"
],
"x-nullable": false
}
},
"example": "Dynamic Field. See Model Definitions",
"oneOf": [
{
"type": "object",
"properties": {
"dto1_field": {
"type": "string",
"x-nullable": false
}
},
"required": [
"dto1_field"
],
"x-nullable": false
},
{
"type": "object",
"properties": {
"dto2_field": {
"type": "string",
"x-nullable": false
}
},
"required": [
"dto2_field"
],
"x-nullable": false
}
]
}
},
"required": [
"dynamic_dto"
]
}
The documentation generator returns the result as a hash, so you can easily modify it based on your needs.
You can override default configurations by changing the values in the config/initializers/dry-swagger.rb
file generated from the rake command in the Installation section.
To modify the descriptions for the Contracts, modify the values in config/locale/dry-swagger.yml
.
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/Jane-Terziev/dry-swagger. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Dry::Swagger project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.