{"id":19226307,"url":"https://github.com/qonto/api_schema","last_synced_at":"2025-04-21T00:32:43.771Z","repository":{"id":56842490,"uuid":"89577264","full_name":"qonto/api_schema","owner":"qonto","description":"DSL for describing APIs and generate swagger json","archived":false,"fork":false,"pushed_at":"2023-06-06T08:41:04.000Z","size":41,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-05-02T00:32:33.023Z","etag":null,"topics":["api","api-schema","documentation","rails","ruby","rubygems"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qonto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-27T08:55:55.000Z","updated_at":"2024-02-29T07:41:27.000Z","dependencies_parsed_at":"2022-09-01T09:03:26.575Z","dependency_job_id":null,"html_url":"https://github.com/qonto/api_schema","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qonto%2Fapi_schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qonto%2Fapi_schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qonto%2Fapi_schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qonto%2Fapi_schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qonto","download_url":"https://codeload.github.com/qonto/api_schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223842528,"owners_count":17212412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-schema","documentation","rails","ruby","rubygems"],"created_at":"2024-11-09T15:18:09.836Z","updated_at":"2024-11-09T15:18:11.375Z","avatar_url":"https://github.com/qonto.png","language":"Ruby","readme":"![Gem Version](https://badge.fury.io/rb/api_schema.svg) ![CI Status](https://github.com/qonto/api_schema/actions/workflows/tests.yml/badge.svg)\n\n# Api Schema\n\nProvides a framework and DSL for describing APIs and generate swagger-json using minimalist, schema.db-like syntax.\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e | \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e | \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'api_schema'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install api_schema\n\n## Usage\n\nJust add `include ApiSchema` and configurations to your base class and inherit from it. You also should define your default `:error_model`\n\n**To generate json use `BaseDocs.generate_json` method.**\n\n#### BaseDocs\n\n```ruby\nmodule V1\n  class BaseDocs\n    include ApiSchema\n\n    configure do |config|\n      config.title = 'Users API'\n      config.description = 'API for users'\n      config.version = '1.0'\n      config.host = 'sample.com'\n      config.base_path = '/api'\n      config.terms_of_service = 'https://sample.com/terms'\n      config.contact_name = 'API Team'\n      config.consumes = 'application/json'\n      config.produces = 'application/json'\n      config.authorization = true\n      config.error_model = :error_model\n      config.error_desc = {\n        '401' =\u003e \"Unauthorized\",\n        '403' =\u003e \"Forbidden\",\n        '404' =\u003e \"Not found\",\n        '422' =\u003e \"Unprocessable Entity\"\n      }\n    end\n\n    serializer :error_model do |f|\n      f.integer :code, required: true\n      f.string :message, required: true\n    end\n  end\nend\n```\n\n#### UsersController\n\n```ruby\nmodule V1\n  module ControllersDocs\n    class UsersController \u003c BaseDocs\n\n      get do\n        path_param :id, :integer\n        name 'Get User'\n        desc 'Returns user with provided id'\n        response 200, :user\n        error! 401, 403, 404, 422\n      end\n    end\n  end\n```\n\n#### UserSerializer\n\n```ruby\nmodule V1\n  module SerializersDocs\n    class UserSerializer \u003c BaseDocs\n\n      serializer :user do |f|\n        f.integer  :id, required: true\n        f.string   :email, required: true\n        f.string   :name\n      end\n    end\n  end\n```\n\n### Serializers\n\nTo describe serializers you can use `serializer` and `array_serializer` methods.\n\n**Here `:user` and `:users` are unique identifiers**\n\nFor **member** responses:\n\n```ruby\nserializer :user do |f|\n  f.integer  :id, required: true\n  f.string   :email, required: true\n  f.string   :name\nend\n```\n\nWill have such a structure:\n\n```json\n{\n  \"user\": {\n    \"id\": 1,\n    \"email\": \"john.doe.gmail.com\",\n    \"name\": \"John Doe\"\n  }\n}\n```\n\nFor **collection** responses:\n\n```ruby\narray_serializer :users do |f|\n  f.reference :meta\n  f.reference :user, type: :array\nend\n```\n\nWill have such a structure:\n\n```json\n{\n  \"meta\": {...},\n  \"users\": [\n    {\n      \"id\": 1,\n      \"email\": \"john.doe.gmail.com\",\n      \"name\": \"John Doe\"\n    },\n    {...}]\n}\n```\n\nThen you can use this descriptions in the controllers with identifiers:\n\n```ruby\nresponse 200, :user\n```\n\n```ruby\nresponse 200, :users\n```\n\n#### References\n\nTo user nested descriptions, you can use `reference` method:\n\n```ruby\nserializer :file do |f|\n  f.integer :file_name, required: true\n  f.string  :file_url, required: true\nend\n```\n\n```ruby\nserializer :attachment do |f|\n  f.integer   :id, required: true\n  f.reference :file\nend\n```\n\n#### Parents\n\nTo inherit fields from another serializer, you can use `parent` parameter:\n\n```ruby\nserializer :file do |f|\n  f.integer   :file_name, required: true\n  f.string    :file_url, required: true\nend\n```\n\n```ruby\nserializer :attachment, parent: :file do |f|\n  f.integer   :id, required: true\nend\n```\n\n### Controllers\n\n#### Endpoints\n\nTo describe endpoints you can use `get`, `post`, `put`, `patch` methods.\n\nGet **collection**:\n\n```ruby\nget do\n  query_param :query, :string\n  query_param :sort_by, :string\n  name 'List Users'\n  desc \"Returns list of the users\"\n  response 200, :users\n  error! 401, 403, 422\nend\n```\n\nWill produce `/users` endpoint.\n\nTo get **member** you should use `path_param` method:\n\n```ruby\nget do\n  path_param :id, :integer\n  name 'Get User'\n  desc 'Returns user with provided id'\n  response 200, :user\n  error! 401, 403, 422\nend\n```\n\nWill produce `/users/{id}` endpoint.\n\nBy default gem uses controller's name to generate endpoints, but you can make custom by passing first argument:\n\n```ruby\nget 'people' do\n  path_param :id, :integer\n  name 'Get User'\n  desc 'Returns user with provided id'\n  response 200, :user\n  error! 401, 403, 422\nend\n```\n\nWill produce `/people/{id}` endpoint.\n\nUse `extra_path` argument to add extra path to the endpoint\n\n```ruby\nget extra_path: :read do\n  path_param :id, :integer\n  name 'Read Notification'\n  desc 'Reads notification with provided id'\n  response 200\n  error! 401, 403, 422\nend\n```\n\nWill produce `/notification/{id}/read` endpoint.\n\n#### Parameters\n\nTo describe each endpoint you can use `header`, `body`, `path_param`, `query_param`\n\n`header` and `body`:\n\n```ruby\npost do\n  header :token, :string\n  body :create_user\n  name 'Create User'\n  desc 'Creates and returns new user'\n  response 200, :user\n  error! 401, 403, 422\nend\n```\n\nTo describe body of the request you can use `request_body` method. It's just an alias for serializer:\n\n```ruby\nrequest_body :create_user do |f|\n  f.string   :email, required: true\n  f.string    :first_name, required: true\n  f.string    :last_name, required: true\nend\n```\n\n## Dependencies\n\n- [Active Support](https://github.com/rails/rails/tree/master/activesupport)\n- [Swagger::Blocks](https://github.com/fotinakis/swagger-blocks)\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n## Releasing\n\nTo publish a new version to rubygems, update the version in `lib/api_schema/version.rb`, and merge.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqonto%2Fapi_schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqonto%2Fapi_schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqonto%2Fapi_schema/lists"}