{"id":15091394,"url":"https://github.com/mikunalpha/goas","last_synced_at":"2025-07-02T03:02:31.946Z","repository":{"id":40557665,"uuid":"134553535","full_name":"mikunalpha/goas","owner":"mikunalpha","description":"Generate OpenAPI Specification from comments","archived":false,"fork":false,"pushed_at":"2022-05-02T20:52:30.000Z","size":79,"stargazers_count":113,"open_issues_count":10,"forks_count":25,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T06:32:03.787Z","etag":null,"topics":["api-documentation","golang","openapi-specification","swagger"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikunalpha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-23T10:30:28.000Z","updated_at":"2024-10-18T10:51:05.000Z","dependencies_parsed_at":"2022-08-09T23:00:53.980Z","dependency_job_id":null,"html_url":"https://github.com/mikunalpha/goas","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/mikunalpha/goas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikunalpha%2Fgoas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikunalpha%2Fgoas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikunalpha%2Fgoas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikunalpha%2Fgoas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikunalpha","download_url":"https://codeload.github.com/mikunalpha/goas/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikunalpha%2Fgoas/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263066557,"owners_count":23408387,"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-documentation","golang","openapi-specification","swagger"],"created_at":"2024-09-25T10:40:55.784Z","updated_at":"2025-07-02T03:02:31.928Z","avatar_url":"https://github.com/mikunalpha.png","language":"Go","readme":"# goas\nThe project is based on  \n- [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) repository.  \n- [uudashr/go-module](https://github.com/uudashr/go-module) repository.\n\nGenerate [OpenAPI Specification](https://swagger.io/specification) json file with comments in Go.\n\n## Limit\n- Only support go module.\n- Anonymous struct field is not supported.\n\n## Install\n\n```\ngo get -u github.com/mikunalpha/goas\n```\n\n## Usage\n\nYou can document your service by placing annotations inside your godoc at various places in your code.\n\n### Service Description\n\nThe service description comments can be located in any of your .go files. They provide general information about the service you are documenting.\n\n```go\n// @Version 1.0.0\n// @Title Backend API\n// @Description API usually works as expected. But sometimes its not true.\n// @ContactName Abcd\n// @ContactEmail abce@email.com\n// @ContactURL http://someurl.oxox\n// @TermsOfServiceUrl http://someurl.oxox\n// @LicenseName MIT\n// @LicenseURL https://en.wikipedia.org/wiki/MIT_License\n// @Server http://www.fake.com Server-1\n// @Server http://www.fake2.com Server-2\n// @Security AuthorizationHeader read write\n// @SecurityScheme AuthorizationHeader http bearer Input your token\n```\n\n#### Security\n\nIf authorization is required, you must define security schemes and then apply those to the API.\nA scheme is defined using `@SecurityScheme [name] [type] [parameters]` and applied by adding `@Security [scheme-name] [scope1] [scope2] [...]`. \n\nAll examples in this section use `MyApiAuth` as the name. This name can be anything you chose; multiple named schemes are supported.\nEach scheme must have its own name, except for OAuth2 schemes - OAuth2 supports multiple schemes by the same name.\n\nA number of different types is supported, they all have different parameters:\n\n|Type|Description|Parameters|Example|\n|---|---|---|---|\n|HTTP|A HTTP Authentication scheme using the `Authorization` header|scheme: any [HTTP Authentication scheme](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml)|`@SecurityScheme MyApiAuth basic`|\n|APIKey|Authorization by passing an API Key along with the request|in: Location of the API Key, options are `header`, `query` and `cookie`. name: The name of the field where the API Key must be set|`@SecurityScheme MyApiAuth apiKey header X-MyCustomHeader`|\n|OpenIdConnect|Delegating security to a known OpenId server|url: The URL of the OpenId server|`@SecurityScheme MyApiAuth openIdConnect https://example.com/.well-known/openid-configuration`|\n|OAuth2AuthCode|Using the \"Authentication Code\" flow of OAuth2|authorizationUrl, tokenUrl|`@SecurityScheme MyApiAuth oauth2AuthCode /oauth/authorize /oauth/token`| \n|OAuth2Implicit|Using the \"Implicit\" flow of OAuth2|authorizationUrl|`@SecurityScheme MyApiAuth oauth2Implicit /oauth/authorize| \n|OAuth2ResourceOwnerCredentials|Using the \"Resource Owner Credentials\" flow of OAuth2|authorizationUrl|`@SecurityScheme MyApiAuth oauth2ResourceOwnerCredentials /oauth/token| \n|OAuth2ClientCredentials|Using the \"Client Credentials\" flow of OAuth2|authorizationUrl|`@SecurityScheme MyApiAuth oauth2ClientCredentials /oauth/token| \n\nAny text that is present after the last parameter wil be used as the description. For instance `@SecurityScheme MyApiAuth basic Login with your admin credentials`.\n\nOnce all security schemes have been defined, they must be configured. This is done with the `@Security` comment.\nDepending on the `type` of the scheme, scopes (see below) may be supported. *At the moment, it is only possible to configure security for the entire service*.\n\n```go\n// @Security MyApiAuth read_user write_user\n```\n\n##### Scopes\nFor OAuth2 security schemes, it is possible to define scopes using the `@SecurityScope [schema-name] [scope-code] [scope-description]` comment.\n\n```go\n// @SecurityScope MyApiAuth read_user Read a user from the system\n// @SecurityScope MyApiAuth write_user Write a user to the system\n```\n\n### Handler funcs\n\nBy adding comments to your handler func godoc, you can document individual actions as well as their input and output.\n\n```go\ntype User struct {\n  ID   uint64 `json:\"id\" example:\"100\" description:\"User identity\"`\n  Name string `json:\"name\" example:\"Mikun\"` \n}\n\ntype UsersResponse struct {\n  Data []Users `json:\"users\" example:\"[{\\\"id\\\":100, \\\"name\\\":\\\"Mikun\\\"}]\"`\n}\n\ntype Error struct {\n  Code string `json:\"code\"`\n  Msg  string `json:\"msg\"`\n}\n\ntype ErrorResponse struct {\n  ErrorInfo Error `json:\"error\"`\n}\n\n// @Title Get user list of a group.\n// @Description Get users related to a specific group.\n// @Param  groupID  path  int  true  \"Id of a specific group.\"\n// @Success  200  object  UsersResponse  \"UsersResponse JSON\"\n// @Failure  400  object  ErrorResponse  \"ErrorResponse JSON\"\n// @Resource users\n// @Route /api/group/{groupID}/users [get]\nfunc GetGroupUsers() {\n  // ...\n}\n\n// @Title Get user list of a group.\n// @Description Create a new user.\n// @Param  user  body  User  true  \"Info of a user.\"\n// @Success  200  object  User           \"UsersResponse JSON\"\n// @Failure  400  object  ErrorResponse  \"ErrorResponse JSON\"\n// @Resource users\n// @Route /api/user [post]\nfunc PostUser() {\n  // ...\n}\n```\n\n#### Title \u0026 Description\n```\n@Title {title}\n@Title Get user list of a group.\n\n@Description {description}.\n@Description Get users related to a specific group.\n```\n- {title}: The title of the route.\n- {description}: The description of the route.\n\n#### Parameter\n```\n@Param  {name}  {in}  {goType}  {required}  {description}\n@Param  user    body  User      true        \"Info of a user.\"\n```\n- {name}: The parameter name.\n- {in}: The parameter is in `path`, `query`, `form`, `header`, `cookie`, `body` or `file`.\n- {goType}: The type in go code. This will be ignored when {in} is `file`.\n- {required}: `true`, `false`, `required` or `optional`. \n- {description}: The description of the parameter. Must be quoted.\n\n#### Response\n```\n@Success  {stauts}  {jsonType}  {goType}       {description}\n@Success  200       object      UsersResponse  \"UsersResponse JSON\"\n\n@Failure  {stauts}  {jsonType}  {goType}       {description}\n@Failure  400       object      ErrorResponse  \"ErrorResponse JSON\"\n```\n- {status}: The HTTP status code.\n- {jsonType}: The value can be `object` or `array`. \n- {goType}: The type in go code.\n- {description}: The description of the response. Must be quoted.\n\n#### Resource \u0026 Tag\n```\n@Resource {resource}\n@Resource users\n\n@Tag {tag}\n@tag xxx\n```\n- {resource}, {tag}: Tag of the route.\n\n#### Route\n```\n@Route {path}    {method}\n@Route /api/user [post]\n```\n- {path}: The URL path.\n- {method}: The HTTP Method. Must be put in brackets.\n\n### Documentation Generation\n\nGo to the folder where is main.go in\n```\n// go.mod and main file are in the same directory\ngoas --module-path . --output oas.json\n\n// go.mod and main file are in the different directory\ngoas --module-path . --main-file-path ./cmd/xxx/main.go --output oas.json\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikunalpha%2Fgoas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikunalpha%2Fgoas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikunalpha%2Fgoas/lists"}