create swagger_blocks files through your models
Add this line to your application's Gemfile:
gem 'swagger_blocks_generator'And then execute:
$ bundle
Or install it yourself as:
$ gem install swagger_blocks_generator
$ rails g swagger_blocks:doc User
creates the documentation based on the return of gem fast_json_api https://github.com/Netflix/fast_jsonapi
$ rails g swagger_blocks:doc User --fast-json-api
$ rails g swagger_blocks:doc User
app/controllers/docs/user.rb
class User
include Swagger::Blocks
swagger_schema :user_index_response do
key :type, :array
items do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :user_show_response do
key :type, :array
items do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :user_create_response do
key :type, :array
items do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :user_update_response do
key :type, :array
items do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :create_user do
property :user do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :update_user do
property :user do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
endapp/controllers/docs/users_controller.rb
class UsersController
include Swagger::Blocks
swagger_path "/users" do
operation :get do
key :summary, "Index users"
key :produces, [
"application/json"
]
key :tags, [
"user"
]
response 200 do
key :description, "User of all users"
schema do
key :"$ref", :user_index_response
end
end
response 401 do
key :description, "Unauthorized"
end
response 403 do
key :description, "Forbidden"
end
response :default do
key :description, "Unexpected error"
end
end
end
swagger_path "/users/{id}" do
operation :get do
key :summary, "Show user"
key :produces, [
"application/json"
]
key :tags, [
"user"
]
parameter do
key :name, :id
key :in, :path
key :description, "id of user"
key :required, true
key :type, :integer
end
response 200 do
key :description, "Show user"
schema do
key :"$ref", :user_show_response
end
end
response 401 do
key :description, "Unauthorized"
end
response 403 do
key :description, "Forbidden"
end
response :default do
key :description, "Unexpected error"
end
end
end
swagger_path "/users" do
operation :post do
key :summary, "Create user"
key :produces, [
"application/json"
]
key :tags, [
"user"
]
parameter do
key :name, :user_params
key :in, :body
key :required, true
schema do
key :"$ref", :create_user
end
end
response 200 do
key :description, "user"
schema do
key :"$ref", :user_create_response
end
end
response 401 do
key :description, "Unauthorized"
end
response 403 do
key :description, "Forbidden"
end
response :default do
key :description, "Unexpected error"
end
end
end
swagger_path "/users/{id}" do
operation :put do
key :summary, "Update user"
key :produces, [
"application/json"
]
key :tags, [
"user"
]
parameter do
key :name, :id
key :in, :path
key :description, "id of user"
key :required, true
key :type, :integer
end
parameter do
key :name, :user_params
key :in, :body
key :required, true
schema do
key :"$ref", :update_user
end
end
response 200 do
key :description, "user"
schema do
key :"$ref", :user_create_response
end
end
response 401 do
key :description, "Unauthorized"
end
response 403 do
key :description, "Forbidden"
end
response :default do
key :description, "Unexpected error"
end
end
end
swagger_path "/users/{id}" do
operation :delete do
key :summary, "Delete user"
key :produces, [
"application/json"
]
key :tags, [
"user"
]
parameter do
key :name, :id
key :in, :path
key :description, "id of user"
key :required, true
key :type, :integer
end
response 200 do
key :description, "empty"
end
response 401 do
key :description, "Unauthorized"
end
response 403 do
key :description, "Forbidden"
end
response :default do
key :description, "Unexpected error"
end
end
end
endapp/controllers/docs/user.rb
class User
include Swagger::Blocks
swagger_schema :user_index_response do
property :data do
key :type, :array
items do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
property :attributes do
items do
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
end
end
property :relationships do
items do
property :posts do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
end
end
end
end
end
end
end
swagger_schema :user_show_response do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
property :attributes do
items do
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
end
end
property :relationships do
items do
property :posts do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
end
end
end
end
end
end
swagger_schema :user_create_response do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
property :attributes do
items do
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
end
end
property :relationships do
items do
property :posts do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
end
end
end
end
end
end
swagger_schema :user_update_response do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
property :attributes do
items do
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
end
end
property :relationships do
items do
property :posts do
property :data do
property :id do
key :type, :integer
end
property :type do
key :type, :string
end
end
end
end
end
end
end
swagger_schema :create_user do
property :user do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
swagger_schema :update_user do
property :user do
property :id do
key :type, :string
end
property :name do
key :type, :string
end
property :created_at do
key :type, :string
end
property :updated_at do
key :type, :string
end
end
end
endBug reports and pull requests are welcome on GitHub at https://github.com/g13ydson/swagger_blocks_generator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the SwaggerBlocksGenerator project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.