{"id":15587653,"url":"https://github.com/icyleaf/swagger","last_synced_at":"2025-10-05T20:49:58.935Z","repository":{"id":53546628,"uuid":"158775620","full_name":"icyleaf/swagger","owner":"icyleaf","description":"Swagger contains a OpenAPI / Swagger universal documentation generator and HTTP server handler.","archived":false,"fork":false,"pushed_at":"2024-04-22T19:52:30.000Z","size":3938,"stargazers_count":41,"open_issues_count":4,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-24T04:49:35.308Z","etag":null,"topics":["crystal","crystal-api-document","crystal-http-handler","swagger","swagger-documentation","swagger-generator"],"latest_commit_sha":null,"homepage":"","language":"Crystal","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/icyleaf.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,"zenodo":null}},"created_at":"2018-11-23T03:18:48.000Z","updated_at":"2024-07-17T23:01:59.000Z","dependencies_parsed_at":"2025-04-24T04:59:43.378Z","dependency_job_id":null,"html_url":"https://github.com/icyleaf/swagger","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/icyleaf/swagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fswagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fswagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fswagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fswagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icyleaf","download_url":"https://codeload.github.com/icyleaf/swagger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icyleaf%2Fswagger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278518559,"owners_count":26000177,"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","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["crystal","crystal-api-document","crystal-http-handler","swagger","swagger-documentation","swagger-generator"],"created_at":"2024-10-02T22:02:44.799Z","updated_at":"2025-10-05T20:49:58.913Z","avatar_url":"https://github.com/icyleaf.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger\n\n[![Language](https://img.shields.io/badge/language-crystal-776791.svg)](https://github.com/crystal-lang/crystal)\n[![Tag](https://img.shields.io/github/tag/icyleaf/swagger.svg)](https://github.com/icyleaf/swagger/blob/master/CHANGELOG.md)\n[![Source](https://img.shields.io/badge/source-github-brightgreen.svg)](https://github.com/icyleaf/swagger/)\n[![Document](https://img.shields.io/badge/document-api-brightgreen.svg)](https://icyleaf.github.io/swagger/)\n[![Build Status](https://img.shields.io/circleci/project/github/icyleaf/swagger/master.svg?style=flat)](https://circleci.com/gh/icyleaf/swagger)\n\nSwagger is a low-level library which generates a document compatible with [Swagger / OpenAPI Spec 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md),\nand wrapped many friendly APIs let developer understand and use it easier.\n\n## Installation\n\n```yaml\ndependencies:\n  swagger:\n    github: icyleaf/swagger\n```\n\n## Quick look\n\n```crystal\nrequire \"swagger\"\n\nbuilder = Swagger::Builder.new(\n  title: \"App API\",\n  version: \"1.0.0\",\n  description: \"This is a sample api for users\",\n  terms_url: \"http://yourapp.com/terms\",\n  contact: Swagger::Contact.new(\"icyleaf\", \"icyleaf.cn@gmail.com\", \"http://icyleaf.com\"),\n  license: Swagger::License.new(\"MIT\", \"https://github.com/icyleaf/swagger/blob/master/LICENSE\"),\n  authorizations: [\n    Swagger::Authorization.jwt(description: \"Use JWT Auth\"),\n  ]\n)\n\nbuilder.add(Swagger::Controller.new(\"Users\", \"User resources\", [\n  Swagger::Action.new(\"get\", \"/users\", description: \"All users\", responses: [\n    Swagger::Response.new(\"200\", \"Success response\")\n  ]),\n  Swagger::Action.new(\"get\", \"/users/{id}\", description: \"Get user by id\", parameters: [\n    Swagger::Parameter.new(\"id\", \"path\")\n  ], responses: [\n    Swagger::Response.new(\"200\", \"Success response\"),\n    Swagger::Response.new(\"404\", \"Not found user\")\n  ], authorization: true),\n  Swagger::Action.new(\"post\", \"/users\", description: \"Create User\", responses: [\n    Swagger::Response.new(\"201\", \"Return user resource after created\"),\n    Swagger::Response.new(\"401\", \"Unauthorizated\")\n  ], authorization: false)\n]))\n\ndocument = builder.built\nputs document.to_json\n```\n\n## Structure\n\nStructure in `src` directory:\n\n```\n.\n├── xxx.cr                        # Friendly APIs\n├── http                          # HTTP assets and libraries\n└── objects                       # OpenAPI objects\n```\n\n## Running on web\n\nSwagger provids a built-in web server, if you have no idea how to preview it:\n\n###\n```crystal\nrequire \"swagger\"\nrequire \"swagger/http/server\"\n\n# made your document (See `builder` code example above)\ndocument = builder.built\n\n# Run web server\nSwagger::HTTP::Server.run(document)\n```\n\n## Integrating\n\nSwagger has two HTTP handlers which you can integrate it to bult-in HTTP Server and mostly frameworks (like kemal, amber, lucky etc):\n\n- Swagger::HTTP::APIHandler\n- Swagger::HTTP::WebHandler\n\n## Examples\n\nSee more [examples](/examples).\n\n## Todo\n\n- [x] openapi\n- [x] Info Object\n- [x] Paths Object\n  - [x] PathItem Object\n    - [x] Parameter Object\n    - [x] RequestBody Object\n    - [x] Responses Object\n    - [x] Security Object\n    - [x] Tag Object\n- [x] Tags Object\n- [x] Servers Objec\n  - [x] ServerVariables Object\n- [x] Security Object\n- [x] Components Object\n  - [x] Schemas Object\n  - [x] SecuritySchemes Object\n    - [x] Basic\n    - [x] Bearer (include JWT)\n    - [x] APIKey\n    - [x] OAuth2\n- [x] ExternalDocs Object\n\n## How to Contribute\n\nYour contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.\n\nHere is a throughput graph of the repository for the last few weeks:\n\nAll [Contributors](https://github.com/icyleaf/swagger/graphs/contributors) are on the wall.\n\n## You may also like\n\n- [halite](https://github.com/icyleaf/halite) - HTTP Requests Client with a chainable REST API, built-in sessions and middlewares.\n- [totem](https://github.com/icyleaf/totem) - Load and parse a configuration file or string in JSON, YAML, dotenv formats.\n- [markd](https://github.com/icyleaf/markd) - Yet another markdown parser built for speed, Compliant to CommonMark specification.\n- [poncho](https://github.com/icyleaf/poncho) - A .env parser/loader improved for performance.\n- [popcorn](https://github.com/icyleaf/popcorn) - Easy and Safe casting from one type to another.\n- [fast-crystal](https://github.com/icyleaf/fast-crystal) - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.\n\n## License\n\n[MIT License](https://github.com/icyleaf/swagger/blob/master/LICENSE) © icyleaf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficyleaf%2Fswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficyleaf%2Fswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficyleaf%2Fswagger/lists"}