{"id":20364117,"url":"https://github.com/artheus/swaggable","last_synced_at":"2026-04-25T11:36:12.633Z","repository":{"id":149726544,"uuid":"143749347","full_name":"artheus/swaggable","owner":"artheus","description":"Simple language to generate larger swagger specs for code generation","archived":false,"fork":false,"pushed_at":"2018-11-07T09:13:27.000Z","size":42,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-03T00:05:03.326Z","etag":null,"topics":["antlr","go","swaggable","swagger","swagger-generator","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artheus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-08-06T15:39:09.000Z","updated_at":"2019-08-26T10:57:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"21806029-c699-466a-9b6f-8250a5334862","html_url":"https://github.com/artheus/swaggable","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/artheus/swaggable","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artheus%2Fswaggable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artheus%2Fswaggable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artheus%2Fswaggable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artheus%2Fswaggable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artheus","download_url":"https://codeload.github.com/artheus/swaggable/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artheus%2Fswaggable/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32261117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["antlr","go","swaggable","swagger","swagger-generator","yaml"],"created_at":"2024-11-15T00:09:53.059Z","updated_at":"2026-04-25T11:36:12.606Z","avatar_url":"https://github.com/artheus.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swaggable\n\nSimple language to generate larger swagger specs for code generation.\n\nThe idea behind this is to create a minimal model definition for a CRUD api (incl api-client) which will expand into a larger specification which will act as the base for code generation. This way, people won't have to write much for just creating a simple Restful CRUD API service.\n\n# Swaggable syntax\n\nSince this implements a DSL for generating Swagger specifications, I feel the need to explain the syntax a bit.\n\n## Types\n\nAll types specified in OpenApi are available. These are:\n* string (this includes dates and files)\n* number\n* integer\n* boolean\n* array\n* object\n\nAs parameters in the swaggable syntax there are two that stands out. It is `array` and `object`\n\n### Arrays\n\nThe syntax for creating an array parameter in swaggable is `array\u003cstring\u003e stringArray` where `array` is the\nparameter type identifier, `string` is the array item type and `stringArray` is the name of the parameter.\n\n### Objects\n\nYou will never write `object` as the type of a parameter in Swaggable. You rather use the name of an other\ncomponent as the type identifier for the parameter. E.g: `MyComponent parameterName`\n\n## Annotations\n\nWhen is comes to indexed fields (eg. searchables) and string formats I decided to go with simple annotations.\nThere are several examples of this in `example/employers`. See the examples below, or the example model source for syntax.\n\nThe available annotations are:\n* __required__ - flags a parameter as required\n* __indexed__ - indexed field, which will be used for referring to a persisted component instance through the final API\n* __format.*__ - the string formats specified in Swagger documentation\n\n## Base components\n\nAs in the `example/employers` script, there are two base components. The meaning of having these is to\nhave extendable components that should not be part of the Swagger specification components.\n\nOther components can extends these bases, and will in the output have all the parameters of the base.\n\nFrom `example/employers` \n```\nbase Entity {\n  number id `required indexed`\n  string created `format.datetime`\n  string updated `format.datetime`\n  Employee createdBy\n  Employee updatedBy\n}\n```\n\n## Regular components\n\nAll of the regular components will turn up in the OpenApi output in `#/components/schemas`\n\nInheritance can work two ways. Either inherit from a base component, which in the output will only\nadd the parameters from the base component. Or inherit from a regular component, which till use\nthe OpenApi type inheritance, because both models will exist in the same specification.\n\nFrom `example/employers`, a regular component inheriting from a base component:\n```\ncomp Key \u003c Entity {\n  Employee employee\n  Customer customer `required`\n  string position `required`\n  array\u003cNote\u003e notes\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartheus%2Fswaggable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartheus%2Fswaggable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartheus%2Fswaggable/lists"}