{"id":21179039,"url":"https://github.com/spaceavocado/apidoc","last_synced_at":"2025-09-05T01:39:34.263Z","repository":{"id":57503718,"uuid":"168361295","full_name":"spaceavocado/apidoc","owner":"spaceavocado","description":"Generate RESTful API documentation from GO source files into the OpenAPI v3.0.2 specification (formal Swagger 2.0 Specification).","archived":false,"fork":false,"pushed_at":"2019-03-26T14:48:21.000Z","size":175,"stargazers_count":17,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-10T00:39:53.785Z","etag":null,"topics":["go","openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"","language":"Go","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/spaceavocado.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-30T15:00:04.000Z","updated_at":"2023-10-13T20:53:04.000Z","dependencies_parsed_at":"2022-08-28T02:00:36.528Z","dependency_job_id":null,"html_url":"https://github.com/spaceavocado/apidoc","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/spaceavocado/apidoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceavocado%2Fapidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceavocado%2Fapidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceavocado%2Fapidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceavocado%2Fapidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spaceavocado","download_url":"https://codeload.github.com/spaceavocado/apidoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spaceavocado%2Fapidoc/sbom","scorecard":{"id":839891,"data":{"date":"2025-08-11","repo":{"name":"github.com/spaceavocado/apidoc","commit":"e05fdde9b8213c72d1710217578792b41e167aa0"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 0/26 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}}]},"last_synced_at":"2025-08-23T20:12:24.032Z","repository_id":57503718,"created_at":"2025-08-23T20:12:24.032Z","updated_at":"2025-08-23T20:12:24.032Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273699716,"owners_count":25152284,"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-09-04T02:00:08.968Z","response_time":61,"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":["go","openapi","openapi3","swagger"],"created_at":"2024-11-20T17:28:03.489Z","updated_at":"2025-09-05T01:39:29.249Z","avatar_url":"https://github.com/spaceavocado.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# APIDoc\n\u003e Current version: beta-0.3.3\n\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"apidoc\" src=\"https://github.com/spaceavocado/apidoc/raw/master/assets/apidoc.png\" width=\"240\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Generate RESTful API documentation from GO source files into the \u003ca href=\"https://swagger.io/specification/\"\u003eOpenAPI v3.0.2\u003c/a\u003e specification (formal Swagger 2.0 Specification).\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://travis-ci.org/spaceavocado/apidoc.svg?branch=master\"\u003e\u003cimg alt=\"Travis Status\" src=\"https://travis-ci.org/spaceavocado/apidoc.svg?branch=master\"\u003e\u003c/a\u003e \u003ca href=\"https://codecov.io/gh/spaceavocado/apidoc\"\u003e\n  \u003cimg src=\"https://codecov.io/gh/spaceavocado/apidoc/branch/master/graph/badge.svg\" /\u003e\n\u003c/a\u003e \u003ca href=\"https://goreportcard.com/badge/github.com/spaceavocado/apidoc\"\u003e\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/spaceavocado/apidoc\"\u003e\u003c/a\u003e \u003ca href=\"https://www.codacy.com/app/davidhorak/apidoc?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=spaceavocado/apidoc\u0026amp;utm_campaign=Badge_Grade\"\u003e\u003cimg src=\"https://api.codacy.com/project/badge/Grade/ed701d5e42f3426d832de973906ba19b\"/\u003e\u003c/a\u003e \u003ca href=\"https://app.fossa.io/projects/git%2Bgithub.com%2Fspaceavocado%2Fapidoc?ref=badge_shield\" alt=\"FOSSA Status\"\u003e\u003cimg src=\"https://app.fossa.io/api/projects/git%2Bgithub.com%2Fspaceavocado%2Fapidoc.svg?type=shield\"/\u003e\u003c/a\u003e \u003ca href=\"https://godoc.org/github.com/spaceavocado/apidoc\"\u003e\u003cimg alt=\"Go Doc\" src=\"https://godoc.org/github.com/spaceavocado/apidoc?status.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n- [APIDoc](#apidoc)\n  - [Table of Contents](#table-of-contents)\n  - [Summary](#summary)\n  - [Examples](#examples)\n  - [Getting Started](#getting-started)\n- [API Annotation in Comments](#api-annotation-in-comments)\n  - [Main Section](#main-section)\n    - [Supported Tags](#supported-tags)\n    - [Example](#example)\n  - [An Endpoint](#an-endpoint)\n    - [Supported Tags](#supported-tags-1)\n    - [Param Tag](#param-tag)\n      - [name](#name)\n      - [in](#in)\n      - [type](#type)\n    - [Body Tag](#body-tag)\n      - [reference](#reference)\n    - [Wrapper Tag](#wrapper-tag)\n      - [Example](#example-1)\n    - [Response Tag](#response-tag)\n      - [code](#code)\n      - [type](#type-1)\n      - [reference](#reference-1)\n    - [Path Tag](#path-tag)\n      - [path](#path)\n      - [method](#method)\n    - [Example Endpoint Annotation](#example-endpoint-annotation)\n  - [gorilla/mux Handler Functions](#gorillamux-handler-functions)\n    - [Notes](#notes)\n  - [gorilla/mux Subrouter](#gorillamux-subrouter)\n    - [Subrouter Annotation](#subrouter-annotation)\n      - [Example](#example-2)\n  - [Mime Types Annotation](#mime-types-annotation)\n  - [Struct Annotation](#struct-annotation)\n  - [Data Types Conversion](#data-types-conversion)\n- [Tips](#tips)\n  - [Annotation over Multiple Lines](#annotation-over-multiple-lines)\n  - [Array References](#array-references)\n  - [And Endpoint With Many Decralarions](#and-endpoint-with-many-decralarions)\n    - [Example](#example-3)\n- [APIDoc CLI](#apidoc-cli)\n- [About the Project](#about-the-project)\n- [Contributing](#contributing)\n  - [Pull Request Process](#pull-request-process)\n- [License](#license)\n\n## Summary\nAPIDoc extracts the API documentation annotation from your GO source files, recursively resoles struct references, and it generates the YAML [OpenAPI v3.0.2](https://swagger.io/specification/) spec. file, which could be tested in the [Swagger Editor](https://editor.swagger.io/) and quickly integrated with [Swagger UI](https://swagger.io/tools/swagger-ui/download/).\n\nThe generator is also able to read [gorilla/mux](https://github.com/gorilla/mux) **Handler** and **HandlerFunc** func signature to automatically generate the `@router` tag, and `@param` tag/s. [See gorilla/mux Handler Functions](#gorillamux-handler-functions).\n\n\u003e Note: It does not generate/support all OpenAPI v3.0.2 blocks, the tool handles just a subset required by our internal needs, it might be extended if there will be high demand on extension, or if anyone would like to contribute.\n\n## Examples\n[Basic API Project](https://github.com/spaceavocado/apidoc/tree/master/example)\n\n## Getting Started\n1. Add annotation into your API source code files, [See API Annotation in Comments](#api-annotation-in-comments).\n   \n2. Get the APIDoc by using:\n    ```sh\n    go get -u github.com/spaceavocado/apidoc\n    ```\n    \u003e This will create a binary in your **$GOPATH/bin** folder called `apidoc` (Mac/Unix) or `apidoc.exe` (Windows).\n\n3. Now you can run `apidoc` command from your shell.\n   \u003e Make sure that **$GOPATH/bin** is in your Environment Variables:\n    - **Linux**:\n      ```sh\n      export PATH=$PATH:$GOPATH/bin\n      ```\n      *Note*: assumption that your have correctly set $GOPATH env. variable.\n\n    - **Windows**: \"Control Panel\" \u003e \"System\" \u003e \"Edit the system environment variables\" \u003e \"Advanced\" \u003e \"Environment Variables\" \u003e \"Path\" \u003e \"Edit\". and add the directory.\n\n4. Run `apidoc` in the your project's root folder. This will extract and process your annotation and it generates the output YAML file.\n    ```sh\n    apidoc -m main.go -e handler -o docs/api\n    ```\n    *Note*: the example shows the default flag values, for more details, [See APIDoc CLI](#apidoc-cli).\n\n5. Preview the documentation in the [Swagger Editor](https://editor.swagger.io/), i.e. put the openapi.yaml content into the editor.\n\n# API Annotation in Comments\nAn API annotation is represented as an code comment starting with **@** symbol followed by documentation tag and it value or parameters. Examples:\n\n* `// @title Example RESTful API`, tag **title** with value \"Example RESTful API\"\n* `// @server api.domain.com/v3 Production`, tag **server** with params: \"api.domain.com/v3\", \"Production\" \n\nThe the value of the tag or the last parameter of the tag captures the multiline comments, example:\n```go\n// @desc Lorem ipsum dolor sit amet, consectetur adipiscing\n// elit. Nullam rhoncus magna nunc, in faucibus metus pulvinar\n// et. Mauris pellentesque \n```\n\u003e The value of desc tag is captured as: \"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam rhoncus magna nunc, in faucibus metus pulvinar et. Mauris pellentesque\"\n```go\n// @server api.domain.com/v3 Lorem ipsum dolor sit amet, consectetur\n// elit. Nullam rhoncus magna nunc.\n```\n\u003e The last parameter, **description** of the server tag is captured as: \"Lorem ipsum dolor sit amet, consectetur elit. Nullam rhoncus magna nunc.\"\n  \n## Main Section\nThis section should be located in the **main** file, passed to the [APIDoc CLI](#apidoc-cli) in **-m** flag (defaults to **main.go**).\n\n### Supported Tags\n\u003e Note: **()** within **Annotation** indicates an annotation parameter captured by the generator.\n\n| Annotation                 | Description                                                                                             | OpenAPI Spec.                                                      | Example                                                      |\n| -------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |\n| title (value)              | **REQUIRED**. The title of the application.                                                             | https://swagger.io/specification/#infoObject field: title          | // @title Example RESTful API                                |\n| desc (value)               | A short description of the application.                                                                 | https://swagger.io/specification/#infoObject field: description    | // @desc An example of publicly accessible API               |\n| ver (value)                | **REQUIRED**. The version of the OpenAPI document                                                       | https://swagger.io/specification/#infoObject field: version        | // @ver 1.0.0                                                |\n| terms (value)              | A URL to the Terms of Service for the API.                                                              | https://swagger.io/specification/#infoObject field: termsOfService | // @terms https://domain.com/api/terms                       |\n| contact.name (value)       | The identifying name of the contact person/organization.                                                | https://swagger.io/specification/#contactObject field: name        | // @contact.name API Support                                 |\n| contact.url (value)        | The URL pointing to the contact information.                                                            | https://swagger.io/specification/#contactObject field: url         | // @contact.url https://domain.com/api/support               |\n| contact.email (value)      | The email address of the contact person/organization.                                                   | https://swagger.io/specification/#contactObject field: email       | // @contact.email support@domain.com                         |\n| lic.name (value)           | The license name used for the API.                                                                      | https://swagger.io/specification/#licenseObject field: name        | // @lic.name Apache 2.0                                      |\n| lic.url (value)            | A URL to the license used for the API.                                                                  | https://swagger.io/specification/#licenseObject field: url         | // @lic.url https://www.apache.org/licenses/LICENSE-2.0.html |\n| server (url) (description) | An object representing a Server \u003cbr\u003e\u003cbr\u003eNote: There might be many @server tags within the main section. | https://swagger.io/specification/#serverObject                     | // @server api.domain.com/v3 Production                      |\n\n### Example\n```go\n// @title An example authentication API\n// @desc Publicly accessible authentication REST API.\n// @terms https://domain.com/docs/api/terms\n//\n// @contact.name API Support\n// @contact.url https://domain.com/contact\n// @contact.email support@domain.com\n//\n// @lic.name Apache 2.0\n// @lic.url https://www.apache.org/licenses/LICENSE-2.0.html\n//\n// @ver 1.0\n// @server https://auth.domain.com/v3 Production API\n// @server https://auth.dev.domain.com/v3 Development API\nfunc main() {}\n```\n\n## An Endpoint\nAn endpoint is being considered as a API comment annotation block found within any file located inside the **endpoints** root folder, passed to the [APIDoc CLI](#apidoc-cli) in **-e** flag (defaults to **./**).\n\u003e For better performance is highly recommended to pass the endpoints root folder as a flag to the CLI to avoid unnecessary file processing.\n\n### Supported Tags\n\u003e Note: **()** within **Annotation** indicates an annotation parameter captured by the generator.\n\n| Annotation                                                 | Description                                                                                                                                                                                   | OpenAPI Spec.                                                        | Example                                                                                               |\n| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| summary (value)                                            | A short summary of what the operation does.                                                                                                                                                   | https://swagger.io/specification/#operationObject field: summary     | @sumamry Lorem ipsum dolor                                                                            |\n| desc (value)                                               | A verbose explanation of the operation behavior.                                                                                                                                              | https://swagger.io/specification/#operationObject field: description | @desc Lorem ipsum dolor sit amet, consectetur adipiscing eli                                          |\n| id (value)                                                 | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive.                                       | https://swagger.io/specification/#operationObject field: operationId | // @id login                                                                                          |\n| tag (array)                                                | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\u003cbr\u003e\u003cbr\u003eNote: Comma separated value, or a single value. | https://swagger.io/specification/#operationObject field: tags        | // @tag User\u003cbr\u003e\u003cbr\u003e// @tag User, Authentication                                                      |\n| accept (array)                                             | A list of accepted request content mime types\u003cbr\u003e\u003cbr\u003e[See Mime Types Annotation](#mime-types-annotation)                                                                                      | n/a                                                                  | // @accept json\u003cbr\u003e\u003cbr\u003e// @accept application/json, application/x-www-form-urlencoded                 |\n| produce (array)                                            | **REQUIRED**. A list of supported content response mime types\u003cbr\u003e\u003cbr\u003e[See Mime Types Annotation](#mime-types-annotation)                                                                      | n/a                                                                  | // @produce json\u003cbr\u003e\u003cbr\u003e// @produce application/json, application/x-www-form-urlencoded               |\n| param (name) (in) {(type)} (required) (description)        | Describes a single operation parameter. \u003cbr\u003e\u003cbr\u003e[See Param Tag](#param-tag)\u003cbr\u003e\u003cbr\u003eNote: There might be many @param tags within the endpoint block.                                           | https://swagger.io/specification/#parameterObject                    | // @param token path {string} true Security Token                                                     |\n| body (reference)                                           | Describes a single request body.\u003cbr\u003e\u003cbr\u003e[See Body Tag](#body-tag)                                                                                                                             | https://swagger.io/specification/#requestBodyObject                  | //@body model.Login                                                                                   |\n| swrap (reference) (field pointer)                          | Success object wrapper. If this tag is set, any success response object is being wrapped with this object on the desired **pointer field**\u003cbr\u003e\u003cbr\u003e[See Wrapper Tag](#wrapper-tag)             | n/a                                                                  | // @swrap response.Success                                                                            |\n| success (code) {(type)} (reference or empty) (description) | **REQUIRED**. Describes a single success response from an API Operation.\u003cbr\u003e\u003cbr\u003e[See Response Tag](#response-tag)                                                                             | https://swagger.io/specification/#responseObject                     | // @success 200 {object} response.Success OK\u003cbr\u003e\u003cbr\u003e// @success 200 {string} OK                       |\n| fwrap (reference) (field pointer)                          | Failure object wrapper. If this tag is set, any failure response object is being wrapped with this object on the desired **pointer field**\u003cbr\u003e\u003cbr\u003e[See Wrapper Tag](#wrapper-tag)             | n/a                                                                  | // @fwrap response.Error                                                                              |\n| failure (code) {(type)} (reference or empty) (description) | Describes a single failure response from an API Operation.\u003cbr\u003e\u003cbr\u003e[See Response Tag](#response-tag)                                                                                           | https://swagger.io/specification/#responseObject                     | // @failure 401 {object} response.AuthError Unauthorized\u003cbr\u003e\u003cbr\u003e// @failure 401 {string} Unauthorized |\n| subrouter (value)                                          | Name of the subrouter used for this endpoint. \u003cbr\u003e\u003cbr\u003e[See gorilla/mux Subrouter](#gorillamux-subrouter)                                                                                      | n/a                                                                  | // @subrouter user [post]                                                                             |\n| router (path) [(method)]                                   | **REQUIRED**. Describes the operations available on a single path, i.e. endpoint URL\u003cbr\u003e\u003cbr\u003e[See Path Tag](#path-tag)                                                                                       | https://swagger.io/specification/#pathItemObject                     | // @router /login [post]                                                                              |\n\n### Param Tag\n\u003e *Annotation:* param (name) (in) {(type)} (required) (description)\n\nThis section contains detailed information about the **param** tag\n#### name \n* The name of the parameter. Parameter names are case sensitive.\n* If `in` is \"path\", the name field MUST correspond to the associated router url parameter, e.g.:\n   `// @param token path {string} true Security token` must match with `// @router /auth/{token} [get]`\n\n#### in \n* The location of the parameter. Possible values are \"query\", \"header\", \"path\" or \"cookie\".\n\n#### type\n* the outer \"{}\" are used just as visual separators of type field, i.e. their are not required.\n  E.g. `// @param token path {string} true Security token` = `// @param token path string true Security token`\n* Param tag does not support struct type, just base go types, [See Type Mapping](#type-mapping)\n* **Array annotation**: `{[]string}`, `{[]int}`, etc.\n\n### Body Tag\n\u003e *Annotation:* body (reference)\n\n#### reference\n* go structure used as request model, example: `// @body model.Login`\n  \n  ```go\n  // Login struct located in \"model\" package,\n  // referenced in the go file where the endpoint\n  // annotation is set\n  type Login struct {\n    // User's email address\n    Username string `json:\"username\"`\n    Password string\n  }\n  ```\n  will be resolved as:\n  ```yaml\n  schema:\n    type: object\n    parameters:\n      username:\n        type: string\n        description: User's email address\n      password:\n        type: string\n  ```\n* The reference structure is being resolved recursively, i.e. it might contain fields referencing other go struct.\n* [See Struct Annotation](#struct-annotation) for more details.\n\n### Wrapper Tag\n\u003e *Annotation:* swrap (reference) (pointer field), fwrap (reference) (field pointer)\n\nIf this tag is set, any success/failure response object is being wrapped with this object on the desired pointer field. This is useful if you are using a generic API response object with various data field.\n\n#### Example\n```go\ntype APISuccess struct {\n  Status string `json:\"status\"`\n  Data interface{} `json:\"data\"`\n}\ntype Profile struct {\n  Firstname int `json:\"firstname\"`\n  Lastname string `json:\"lastname\"`\n}\n```\n\n`// @swrap APISuccess data` and `// @success 200 {object} Profile OK` will produce:\n```yaml\n\"200\":\n  description: OK\n  content:\n    application/json:\n      schema:\n        type: object\n        properties:\n          status:\n            type: string\n          data:\n            schema:\n              $ref: \"#/components/schemas/Profile\"\n```\n\n* The reference structure is being resolved recursively, i.e. it might contain fields referencing other go struct.\n* [See Struct Annotation](#struct-annotation) for more details.\n\n### Response Tag\n\u003e *Annotation:* success (code) {(type)} (reference or string) (description), failure (code) {(type)} (reference or string) (description)\n\n#### code\n* Any valid HTTP reponse code\n\n#### type\n* The outer \"{}\" are used just as visual separators of type field, i.e. their are not required.\n  E.g. `// @success 200 {string} string OK` = `// @success 200 string string OK`\n* Supported: object, string\n  * if set to object, the next parameter expected is **reference**\n  * if set to string, next parameter is skipped (reference)\n\n#### reference\n* Reference response go struct\n* **Array annotation**: `{[]response.Car}`, etc.\n* The reference structure is being resolved recursively, i.e. it might contain fields referencing other go struct.\n* [See Struct Annotation](#struct-annotation) for more details.\n\n### Path Tag\n\u003e *Annotation:* router (path) [(method)]\n\n#### path \n* It might contain the \"path\" parameters, it this format: `/login/{token}` where token is the name of param defined in the [Param Tag](#patam-tag).\n\n#### method\n* HTTP method\n* The outer \"[]\" are used just as visual separators of method field, i.e. their are not required.\n  E.g. `// @router /login [post]` = `// @router /login post`\n* It might contain an array of methods, e.g.: `[post, put]`\n\n### Example Endpoint Annotation\n```go\n// Login request\n// @summary Login user\n// @desc Authentication request\n// @id login\n// @tag Authentication\n// @accept json, application/x-www-form-urlencoded\n// @produce json\n// @body model.Login\n// @swrap response.Data data\n// @success 200 {object} request.Token OK\n// @failure 401 {object} response.Error Unauthorized.\n// See error code and error message for more details.\n// @failure 500 {string} Internal Server Error\n// @router /login [post]\nfunc handler(w http.ResponseWriter, r *http.Request) {}\n\n// @summary Activate user\n// @desc User activation via the token request.\n// @id activate\n// @tag Registration\n// @param token path {string} true Activation token\n// @produce json\n// @success 200 {string} OK\n// @failure 500 {string} Internal Server Error\n// @router /registration/activate/{token} [get]\nfunc handler(w http.ResponseWriter, r *http.Request) {}\n\n// Handlers with passed gorilla mux router\n//\n// In this example the @router tag is being resolved\n// from the HandleFunc or Handle gorilla *mux.Router func.\n// @param tags ara also resolved from the func path string.\n//\n// These tags will be extracted automatically:\n// @router /person/{id} [get]\n// @param id path {string} true\nfunc Handlers(r *mux.Router) {\n  // GetPerson handler\n  // @summary Person\n  // @desc Get person by ID.\n  // @id person\n  // @tag Person\n  // @produce json\n  // @success 200 {object} Person OK\n  // @failure 500 {string} Internal Server Error\n  r.HandleFunc(\"/person/{id:[0-9]+}\", GetPerson).Methods(\"GET\")\n}\n```\n\n## gorilla/mux Handler Functions\n`@router` tag and  `@param` tags could automatically resolved if the endpoint annotation is placed above the [gorilla/mux](https://github.com/gorilla/mux) Handler or HandlerFunc function:\n```go\n// GetPerson handler\n// @summary Person\n// @desc Get person by ID.\n// @id person\n// @tag Person\n// @produce json\n// @success 200 {object} Person OK\n// @failure 500 {string} Internal Server Error\nr.HandleFunc(\"/person/{id:[0-9]+}\", GetPerson).Methods(\"GET\")\n```\nAutomatically resolved tags will be be:\n* `@router /person/{id} [get]`\n* `@param id path {string} true`\n\n### Notes\n* This process is skipped if the endpoint annotation contains the `@router` tag\n* If the endpoint annotation contains a `@param` tag found in the func path parameter, it is not being overwritten by the this process nor double annotated.\n* Please [see gorilla/mux Subrouter](#gorillamux-subrouter) section for more information how to work with gorilla/mux subrouters.\n\n## gorilla/mux Subrouter\nAn endpoint can use `subrouter` tag to connect a endpoint with the subrouter to resolve the final endpoint URL.\n\n### Subrouter Annotation\n| Annotation       | Description                   | Example             |\n| ---------------- | ----------------------------- | ------------------- |\n| router (name)    | Name of the subrouter.        | // @router account  |\n| subrouter (name) | Name of the parent subrouter. | // @subrouter admin |\n\nThe annotation must be placed above the **gorilla.mux Subrouter** method anywhere within the Main file or in any file within the endpoints root folder.\n\n#### Example\n```go\n// @router admin\nr.PathPrefix(\"/admin\").Subrouter()\n\n// @router user\n// @subrouter admin\nr.PathPrefix(\"/user\").Subrouter()\n\n// @summary List of users\n// @produce json\n// @success 200 {object} Person OK\n// @subrouter user\nr.HandleFunc(\"/list\", GetPersonList).Methods(\"GET\")\n```\n\u003e The URL resolved for the \"List of users\" endpoint will be `/admin/user/list`\n\n## Mime Types Annotation\n| Mime Type                         | Annotation                              |\n| --------------------------------- | --------------------------------------- |\n| text/plain                        | text, text/plain                        |\n| text/html                         | html, text/html                         |\n| text/xml                          | xml, text/xml                           |\n| application/json                  | json, application/json                  |\n| application/x-www-form-urlencoded | form, application/x-www-form-urlencoded |\n| multipart/form-data               | multipart, multipart/form-data          |\n| application/vnd.api+json          | json-api, application/vnd.api+json      |\n| application/x-json-stream         | json-stream, application/x-json-stream  |\n| application/octet-stream          | octet-stream, application/octet-stream  |\n| image/png                         | png, image/png                          |\n| image/jpeg                        | jpeg, image/jpeg                        |\n| image/jpeg                        | jpg,  image/jpeg                        |\n| image/gif                         | gif,  image/gif                         |\n\n## Struct Annotation\n```go\ntype Profile struct {\n  // User's email\n  Username string `json:\"username\" required:\"true\"`\n  Status UserStatus `apitype:\"int\"`\n}\ntype UserStatus int\n```\n\n* Comment above the field is being captured as field \"description\"\n* `json:\"x\"` overrides the field name\n* `apitype:\"x\"` overrides the field type\n* `required:\"true\"` marks the field as required\n\n## Data Types Conversion\nGo types are being converted into OpenAPI accepted format\n\n| go Type | Converted Type |\n| ------- | -------------- |\n| byte    | integer        |\n| rune    | integer        |\n| int     | integer        |\n| int8    | integer        |\n| int16   | integer        |\n| int32   | integer        |\n| int64   | integer        |\n| uint    | integer        |\n| uint8   | integer        |\n| uint16  | integer        |\n| uint32  | integer        |\n| uint64  | integer        |\n| uintptr | integer        |\n| float32 | number         |\n| float64 | number         |\n| bool    | boolean        |\n\n# Tips\n\n## Annotation over Multiple Lines\nLast parameter of any tag is could spread over multiple lines, e.g.:\n```go\n// @desc Lorem ipsum dolor sit amet, consectetur adipiscing\n// elit. Nullam rhoncus magna nunc, in faucibus metus pulvinar\n// et. Mauris pellentesque enim justo\n\n// @failure 500 {string} Lorem ipsum dolor sit amet, consectetur\n// adipiscing elit. Nullam rhoncus magna nunc, in faucibus metus\n// pulvinar et. Mauris pellentesque enim justo.\n```\n\n## Array References\nUse **[]** annotation in from of the reference.\n```go\n// @body []request.Person\n\n// @success 200 {object} []response.Person OK\n```\n\n## And Endpoint With Many Decralarions\nAn endpoint, with the same URL could be declared separately with different methods, and the generator will properly group them.\n### Example\n```go\n// @summary Get User\n// @param id path {int} true User ID\n// @produce text\n// @success 200 {string} OK\n// @router /user/{id} [post]\n\n// ...\n\n// @summary Delete User\n// @param id path {int} true User ID\n// @produce text\n// @success 200 {string} OK\n// @router /user/{id} [delete]\n```\nwill produce\n```yaml\n/user/{id}:\n  get:\n    summary: Get User\n    parameters:\n    - name: id\n      description: User ID\n      in: path\n      required: true\n      schema:\n        type: integer\n    responses:\n      \"200\":\n        description: OK\n        content:\n          plain/text:\n            schema:\n              type: string\n  delete:\n    summary: Delete User\n    parameters:\n    - name: id\n      description: User ID\n      in: path\n      required: true\n      schema:\n        type: integer\n    responses:\n      \"200\":\n        description: OK\n        content:\n          plain/text:\n            schema:\n              type: string\n```\n\n# APIDoc CLI\nRun the `apidoc -h` to all flags and commands:\n```console\nAPI Documentation Generator\n\nUsage:\n   [flags]\n   [command]\n\nAvailable Commands:\n  help        Help about any command\n  version     Show the APIDoc version\n\nFlags:\n  -e, --endpoints string   Root endpoints folder (default \"./\")\n  -h, --help               Help for this command\n  -m, --main string        Main API documentation file (default \"main.go\")\n  -o, --output string      Documentation output folder (default \"docs/api\")\n  -v, --verbose            Show generation warnings\n\nUse \" [command] --help\" for more information about a command.\n```\n\n# About the Project\nThis project was inspired by [swaggo/swag](https://github.com/swaggo/swag/), designed mainly to handle our API documentation needs, i.e. add support for response wrappers, generate OpenAPI v3.X documentation. Any feedback, contribution to this project is welcomed.\n\nThe project is in a beta phase, therefore there might be major changes in near future, the annotation should stay the same, though.\n\n# Contributing\nWhen contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. \n\n## Pull Request Process\n1. Fork it\n2. Create your feature branch (`git checkout -b ft/new-feature-name`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin ft/new-feature-name`)\n5. Create new Pull Request\n\n\u003e Please make an issue first if the change is likely to increase.\n\n# License\nAPIDoc is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spaceavocado/apidoc/blob/master/LICENSE.txt)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceavocado%2Fapidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspaceavocado%2Fapidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspaceavocado%2Fapidoc/lists"}