{"id":17964816,"url":"https://github.com/inaka/cowboy_swagger","last_synced_at":"2025-12-12T00:28:27.366Z","repository":{"id":34552009,"uuid":"38496998","full_name":"inaka/cowboy_swagger","owner":"inaka","description":"Swagger integration for Cowboy (built on trails)","archived":false,"fork":false,"pushed_at":"2024-06-10T05:38:53.000Z","size":39557,"stargazers_count":121,"open_issues_count":13,"forks_count":58,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-09T22:16:14.470Z","etag":null,"topics":["cowboy-swagger","erlang","hacktoberfest","javascript","swagger"],"latest_commit_sha":null,"homepage":"http://inaka.net/blog/2015/08/19/cowboy-swagger/","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inaka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-03T14:35:48.000Z","updated_at":"2025-03-18T21:49:02.000Z","dependencies_parsed_at":"2022-08-03T21:31:08.631Z","dependency_job_id":"5a235fb1-f7ad-4905-8ef9-5fdd8e9a25a1","html_url":"https://github.com/inaka/cowboy_swagger","commit_stats":{"total_commits":224,"total_committers":30,"mean_commits":7.466666666666667,"dds":0.7455357142857143,"last_synced_commit":"24334d88d76770f32ee0eed2218c94e7e2eb8720"},"previous_names":["inaka/cowboy-swagger"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy_swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy_swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy_swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy_swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inaka","download_url":"https://codeload.github.com/inaka/cowboy_swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119288,"owners_count":21050755,"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":["cowboy-swagger","erlang","hacktoberfest","javascript","swagger"],"created_at":"2024-10-29T12:08:51.583Z","updated_at":"2025-12-12T00:28:27.315Z","avatar_url":"https://github.com/inaka.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://www.braveterry.com/wp-content/uploads/2015/03/swagger2.png\"/\u003e\n\n# cowboy-swagger\n\n[Swagger](https://swagger.io/) integration for [Cowboy](https://github.com/ninenines/cowboy) (built on [trails](https://github.com/inaka/cowboy-trails)).\n\n![build](https://github.com/inaka/cowboy_swagger/workflows/build/badge.svg)\n\n## Contact Us\n\nIf you find any **bugs** or have a **problem** while using this library, please\n[open an issue](https://github.com/inaka/cowboy_swagger/issues/new) in this repo\n(or a pull request :)).\n\n## Why Cowboy Swagger?\n\nSimple, because there isn't a tool in Erlang to document Cowboy RESTful APIs easy and fast,\nand to improve development productivity.\n\nWith `cowboy_swagger` is possible to integrate Swagger to your Erlang projects that use Cowboy as a web server.\nIt is extremely easy to use, and with just a few steps you'll have a nice Web documentation for your RESTful APIs.\n\nTo learn a bit more about Swagger, please check this [blog post](https://web.archive.org/web/20161110235900/https://inaka.net/blog/2015/06/23/erlang-swagger-2015/).\n\n## How to Use it?\n\nThis is the best part. It is extremely easy.\n\n### 1. Document each Cowboy Handler\n\nBecause `cowboy_swagger` runs on top of `trails`, the first thing that you have to do\nis document all about your handler within the trails metadata. Keep in mind that\nall fields defined within each method into the metadata must be compliant with the\n[Swagger specification](https://swagger.io/specification).\n\nFor example, suppose that you have `example_echo_handler`, so it must implement the\n`c:trails_handler:trails/0` callback:\n\n```erlang\ntrails() -\u003e\n  Metadata =\n    #{get =\u003e\n      #{tags =\u003e [\"echo\"],\n        description =\u003e \"Gets echo var from the server\",\n        produces =\u003e [\"text/plain\"]\n      },\n      put =\u003e\n      #{tags =\u003e [\"echo\"],\n        description =\u003e \"Sets echo var in the server\",\n        produces =\u003e [\"text/plain\"],\n        parameters =\u003e [\n          #{name =\u003e \u003c\u003c\"echo\"\u003e\u003e,\n            description =\u003e \u003c\u003c\"Echo message\"\u003e\u003e,\n            in =\u003e \u003c\u003c\"path\"\u003e\u003e,\n            required =\u003e false,\n            type =\u003e \u003c\u003c\"string\"\u003e\u003e}\n        ]\n      }\n    },\n  [trails:trail(\"/message/[:echo]\", example_echo_handler, [], Metadata)].\n```\n\nTo get a better idea of how your handler should look like, please check [`example/src/example_echo_handler.erl`](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example_echo_handler.erl).\n\n### 2. Include cowboy_swagger in your app\n\nFirst, you need to include `cowboy_swagger_handler` module in your list of trails to be compiled.\n\n```erlang\n% Include cowboy_swagger_handler in the trails list\nTrails = trails:trails([example_echo_handler,\n                        example_description_handler,\n                        cowboy_swagger_handler]),\n% store them\ntrails:store(Trails),\n% and then compile them\nDispatch = trails:single_host_compile(Trails),\n```\n\nThe snippet of code above is usually placed when you start `cowboy`. Check it [here](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example.erl).\n\nThen add `cowboy_swagger` to the list of apps to be loaded in your `*.app.src` file.\n\n```erlang\n{application, example,\n [\n  {description, \"Cowboy Swagger Basic Example.\"},\n  {vsn, \"0.1\"},\n  {applications,\n   [kernel,\n    stdlib,\n    jsx,\n    cowboy,\n    trails,\n    cowboy_swagger\n   ]},\n  {modules, []},\n  {mod, {example, []}},\n  {registered, []},\n  {start_phases, [{start_trails_http, []}]}\n ]\n}.\n```\n\nAnd that's it, you got it. Now start your application and then you will have access to the API docs\nunder the path `/api-docs`. Supposing that you're running the app on `localhost:8080`,\nthat will be [http://localhost:8080/api-docs](http://localhost:8080/api-docs).\n\n## Configuration\n\nAdditionally, `cowboy_swagger` can be configured/customized from a `*.config` file:\n\n### app.config\n\n```erlang\n[\n %% Other apps ...\n\n %% cowboy_swagger config\n {cowboy_swagger,\n  [\n   %% `static_files`: Static content directory. This is where Swagger-UI\n   %% is located. Default: `priv/swagger`.\n   %% Remember that Swagger-UI is embedded into `cowboy-swagger` project,\n   %% within `priv/swagger` folder. BUT you have to reference that path,\n   %% and depending on how you're using `cowboy-swagger` it will be different.\n   %% For example, assuming that you want to run your app which has\n   %% `cowboy-swagger` as dependency from the console, `static_files` will be:\n   {static_files, \"./deps/cowboy_swagger/priv/swagger\"},\n\n   %% `global_spec`: Global fields for Swagger specification.\n   %% If these fields are not set, `cowboy_swagger` will set default values.\n   {global_spec,\n    #{swagger =\u003e \"2.0\",\n      info =\u003e #{title =\u003e \"Example API\"},\n      basePath =\u003e \"/api-docs\"\n     }\n   }\n  ]\n }\n].\n```\n\n### Definitions\n\n[Definitions](https://swagger.io/specification/#definitionsObject) can be used for describing\n[parameters](https://swagger.io/specification/#parametersDefinitionsObject),\n[responses](https://swagger.io/specification/#responsesDefinitionsObject) and\n[security](https://swagger.io/specification/#securityDefinitionsObject) schemas.\n\nFor adding definitions to your app, you have 2 choices:\n\n1. Add a `definitions` key to your cowboy_swagger `global_spec` map.\n2. Add them by calling `cowboy_swagger:add_definition/2` and send the\n   definition's name and properties.\n\nLet's say you want to describe a `POST` call to a `newspapers` endpoint that requires\n`name` and `description` fields only, you can do it like this:\n\n**Option 1:**\n\n```erlang\n[ ... % other configurations\n, { cowboy_swagger\n  , [ { global_spec\n      , #{ swagger =\u003e \"2.0\"\n         , info =\u003e #{title =\u003e \"My app API\"}\n         , definitions =\u003e #{\n             \"RequestBody\" =\u003e\n               #{ \"name\" =\u003e\n                   #{ \"type\" =\u003e \"string\"\n                    , \"description\" =\u003e \"Newspaper name\"\n                    }\n                , \"description\" =\u003e\n                    #{ \"type\" =\u003e \"string\"\n                     , \"description\" =\u003e \"Newspaper description\"\n                     }\n                }\n           }\n         }\n      }\n    ]\n  }\n]\n```\n\n**Option 2:**\n\nFor the second choice, you can do it for example in one or several `start_phases`,\ndirectly in your handler or any other place you want.\n\n```erlang\n-spec trails() -\u003e trails:trails().\ntrails() -\u003e\n  DefinitionName = \u003c\u003c\"RequestBody\"\u003e\u003e,\n  DefinitionProperties =\n    #{ \u003c\u003c\"name\"\u003e\u003e =\u003e\n         #{ type =\u003e \u003c\u003c\"string\"\u003e\u003e\n          , description =\u003e \u003c\u003c\"Newspaper name\"\u003e\u003e\n          }\n     , \u003c\u003c\"description\"\u003e\u003e =\u003e\n         #{ type =\u003e \u003c\u003c\"string\"\u003e\u003e\n          , description =\u003e \u003c\u003c\"Newspaper description\"\u003e\u003e\n          }\n     },\n  % Add the definition\n  ok = cowboy_swagger:add_definition(DefinitionName, DefinitionProperties),\n  ...\n```\n\nNow in your handler's trails callback function you can use it:\n\n```erlang\n...\n  RequestBody =\n    #{ name =\u003e \u003c\u003c\"request body\"\u003e\u003e\n     , in =\u003e body\n     , description =\u003e \u003c\u003c\"request body (as json)\"\u003e\u003e\n     , required =\u003e true\n       % Use the previously created `RequestBody' definition\n     , schema =\u003e cowboy_swagger:schema(\u003c\u003c\"RequestBody\"\u003e\u003e)\n     },\n  Metadata =\n    #{ get =\u003e\n       #{ tags =\u003e [\"newspapers\"]\n        , description =\u003e \"Returns the list of newspapers\"\n        , produces =\u003e [\"application/json\"]\n        }\n     , post =\u003e\n       # { tags =\u003e [\"newspapers\"]\n         , description =\u003e \"Creates a new newspaper\"\n         , consumes =\u003e [\"application/json\"]\n         , produces =\u003e [\"application/json\"]\n         , parameters =\u003e [RequestBody] % and then use that parameter here\n         }\n     },\n  Path = \"/newspapers\",\n  Options = #{path =\u003e Path},\n  [trails:trail(Path, newspapers_handler, Options, Metadata)].\n```\n\nWhat this does for you is add a nice `response`, `parameter` or `security`\nmodel in swagger-ui, so client developers will know exactly what parameters\nthe API expects for every endpoint.\n\n## Example\n\nFor more information about `cowboy_swagger` and how to use it, please check this [Example](https://github.com/inaka/cowboy_swagger/tree/master/example).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fcowboy_swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finaka%2Fcowboy_swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fcowboy_swagger/lists"}