{"id":20648518,"url":"https://github.com/lincanbin/apidoc-markdown","last_synced_at":"2025-09-16T15:45:58.989Z","repository":{"id":62517278,"uuid":"124989047","full_name":"lincanbin/apidoc-markdown","owner":"lincanbin","description":"Generate API documentation in markdown format from API annotations in your source code.","archived":false,"fork":false,"pushed_at":"2018-08-29T13:10:55.000Z","size":37,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-13T11:18:45.228Z","etag":null,"topics":["apidoc","documentation","documentation-tool","markdown","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","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/lincanbin.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-03-13T03:49:54.000Z","updated_at":"2024-01-05T15:45:22.000Z","dependencies_parsed_at":"2022-11-02T13:45:33.075Z","dependency_job_id":null,"html_url":"https://github.com/lincanbin/apidoc-markdown","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lincanbin/apidoc-markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincanbin%2Fapidoc-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincanbin%2Fapidoc-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincanbin%2Fapidoc-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincanbin%2Fapidoc-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lincanbin","download_url":"https://codeload.github.com/lincanbin/apidoc-markdown/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincanbin%2Fapidoc-markdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275444048,"owners_count":25466002,"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-16T02:00:10.229Z","response_time":65,"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":["apidoc","documentation","documentation-tool","markdown","php"],"created_at":"2024-11-16T17:09:11.349Z","updated_at":"2025-09-16T15:45:58.944Z","avatar_url":"https://github.com/lincanbin.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# apidoc-markdown\nGenerate API documentation in markdown format from API annotations in your source code.\n\n## Preface\n\nAll examples in this document use the **Javadoc-Style** (can be used in C#, Go, Dart, Java, JavaScript, PHP, TypeScript and all other Javadoc capable languages):\n\n```\n/**\n * This is a comment.\n */\n```\n\n## Install\n\n```shell\ncomposer global require lincanbin/apidoc-markdown:~1.0\n```\n\n## Run\n\n```\napidoc-markdown -i myapp/ -o apidoc/\n```\n\nor\n\n```\napidoc -i myapp/ -o apidoc/\n```\n\nCreates an apiDoc of all files within dir `myapp/`, and put all output to dir `apidoc/`.\n\nWithout any parameter, apiDoc generate a documentation from all `.cs` `.dart` `.erl` `.go` `.java` `.js` `.php` `.py` `.rb` `.ts` files in current dir (incl. subdirs) and writes the output to `./apidoc/`.\n\n## Command Line Interface\n\nShow command line parameters:\n\n```\napidoc-markdown -h\n```\n\nImportant parameters:\n\n| Parameter          | Description                                                  |\n| ------------------ | ------------------------------------------------------------ |\n| -f, --file-filters | RegEx-Filter to select files that should be parsed (many -f can be used). Default `.cs` `.dart` `.erl` `.go` `.java` `.js` `.php` `.py` `.rb` `.ts`.  Example (parse only .js and .ts files): `apidoc -f \".*\\\\.js$\" -f \".*\\\\.ts$\"` |\n| -i, --input        | Input / source dirname. Location of your project files.  Example: `apidoc -i myapp/` |\n| -o, --output       | Output dirname. Location where to put to generated documentation.  Example: `apidoc -o apidoc/` |\n| -t, --template     | Use template for output files. You can create and use your own template.  Example: `apidoc -t mytemplate/` |\n\n## Configuration (apidoc.json)\n\nThe optional `apidoc.json` in your projects root dir includes common information about your project like title, short description, version and configuration options like [header / footer](#headerfooter)settings or template specific options.\n\n[apidoc.json](source/example_full/apidoc.json)\n\n```\n{\n  \"name\": \"example\",\n  \"version\": \"0.1.0\",\n  \"description\": \"apiDoc basic example\",\n  \"title\": \"Custom apiDoc browser title\",\n  \"url\" : \"https://api.github.com/v1\"\n}\n```\n\nIf you use a `package.json` (e.g. in a node.js project), all `apidoc.json` settings can be done in `package.json` too, just add them under the `\"apidoc\": { }` parameter.\n\npackage.json\n\n```\n{\n  \"name\": \"example\",\n  \"version\": \"0.1.0\",\n  \"description\": \"apiDoc basic example\",\n  \"apidoc\": {\n    \"title\": \"Custom apiDoc browser title\",\n    \"url\" : \"https://api.github.com/v1\"\n  }\n}\n```\n\n### Settings for apidoc.json\n\n| Name        | Description                                                  |\n| ----------- | ------------------------------------------------------------ |\n| name        | Name of your project. If no `apidoc.json` with the field exists, then apiDoc try to determine the the value from `package.json`. |\n| version     | Version of your project. If no `apidoc.json` with the field exists, then apiDoc try to determine the the value from `package.json`. |\n| description | Introduction of your project. If no `apidoc.json` with the field exists, then apiDoc try to determine the the value from `package.json`. |\n| title       | Browser title text.                                          |\n| url         | Prefix for api path (endpoints), e.g. `https://api.github.com/v1` |\n| sampleUrl   | If set, a form to test an api method (send a request) will be visible. See [@apiSampleRequest](#param-api-sample-request) for more details. |\n| header      |                                                              |\n| title       | Navigation text for the included header.md file. (watch [Header / Footer](#headerfooter)) |\n| filename    | Filename (markdown-file) for the included header.md file.    |\n| footer      |                                                              |\n| title       | Navigation text for the included footer.md file.             |\n| filename    | Filename (markdown-file) for the included footer.md file.    |\n| order       | A list of api-names / group-names for ordering the output. Not defined names are automatically displayed last. `\"order\": [   \"Error\",   \"Define\",   \"PostTitleAndError\",   \"PostError\" ]` |\n\n### Template specific settings\n\nThe following settings are specific for the default template of apiDoc.\n\n| Name            | Type    | Description                                                  |\n| --------------- | ------- | ------------------------------------------------------------ |\n| template        |         |                                                              |\n| forceLanguage   | String  | Disable browser language auto-detection and set a specific locale. Example: `de`, `en`. View available locales [here](https://github.com/apidoc/apidoc/tree/master/template/locales). |\n| withCompare     | Boolean | Enable comparison with older api versions. Default: `true`   |\n| withGenerator   | Boolean | Output the generator information at the footer. Default: `true` |\n| jQueryAjaxSetup | Object  | Set [default values](http://api.jquery.com/jquery.ajaxsetup/) for Ajax requests. |\n\n## Header / Footer\n\nIn your projects `apidoc.json` you can add a header and footer.\n\nThe title will be visible in the navigation. The filename should be a markdown textfile.\n\n[apidoc.json](source/example_full/apidoc.json)\n\n```\n{\n  \"header\": {\n    \"title\": \"My own header title\",\n    \"filename\": \"header.md\"\n  },\n  \"footer\": {\n    \"title\": \"My own footer title\",\n    \"filename\": \"footer.md\"\n  }\n}\n```\n\n## Basic\n\nIn this basic example we have a small project file and an apidoc.json.\n\n[View example output](example_basic/)\n\n[apidoc.json](source/example_basic/apidoc.json)\n\n```\n{\n  \"name\": \"example\",\n  \"version\": \"0.1.0\",\n  \"description\": \"A basic apiDoc example\"\n}\n```\n\nFrom `apidoc.json` apiDoc get the name, version and description of your project.\nThe file is `optional` (it depend on your template if the data is required).\n\n[example.js](source/example_basic/example.js)\n\n```\n/**\n * @api {get} /user/:id Request User information\n * @apiName GetUser\n * @apiGroup User\n *\n * @apiParam {Number} id Users unique ID.\n *\n * @apiSuccess {String} firstname Firstname of the User.\n * @apiSuccess {String} lastname  Lastname of the User.\n *\n * @apiSuccessExample Success-Response:\n *     HTTP/1.1 200 OK\n *     {\n *       \"firstname\": \"John\",\n *       \"lastname\": \"Doe\"\n *     }\n *\n * @apiError UserNotFound The id of the User was not found.\n *\n * @apiErrorExample Error-Response:\n *     HTTP/1.1 404 Not Found\n *     {\n *       \"error\": \"UserNotFound\"\n *     }\n */\n```\n\nA documentation block starts with `/**` and end with `*/`.\n\nThis example describes a `GET` Method to request the User Information by the user's `id`.\n\n`@api {get} /user/:id Request User information` is mandatory, without `@api`apiDoc ignores a documentation block.\n\n`@apiName` must be a unique name and should always be used.\nFormat: *method* + *path* (e.g. Get + User)\n\n`@apiGroup` should always be used, and is used to group related APIs together.\n\nAll other fields are optional, look at their description under [apiDoc-Params](#params).\n\n## Inherit\n\nUsing inherit, you can define reusable snippets of your documentation.\n\n[View example output](example_inherit/)\n\n[apidoc.json](source/example_inherit/apidoc.json)\n\n```\n{\n  \"name\": \"example-inherit\",\n  \"version\": \"0.1.0\",\n  \"description\": \"apiDoc inherit example\"\n}\n```\n\n[example.js](source/example_inherit/example.js)\n\n```\n/**\n * @apiDefine UserNotFoundError\n *\n * @apiError UserNotFound The id of the User was not found.\n *\n * @apiErrorExample Error-Response:\n *     HTTP/1.1 404 Not Found\n *     {\n *       \"error\": \"UserNotFound\"\n *     }\n */\n\n/**\n * @api {get} /user/:id Request User information\n * @apiName GetUser\n * @apiGroup User\n *\n * @apiParam {Number} id Users unique ID.\n *\n * @apiSuccess {String} firstname Firstname of the User.\n * @apiSuccess {String} lastname  Lastname of the User.\n *\n * @apiSuccessExample Success-Response:\n *     HTTP/1.1 200 OK\n *     {\n *       \"firstname\": \"John\",\n *       \"lastname\": \"Doe\"\n *     }\n *\n * @apiUse UserNotFoundError\n */\n\n/**\n * @api {put} /user/ Modify User information\n * @apiName PutUser\n * @apiGroup User\n *\n * @apiParam {Number} id          Users unique ID.\n * @apiParam {String} [firstname] Firstname of the User.\n * @apiParam {String} [lastname]  Lastname of the User.\n *\n * @apiSuccessExample Success-Response:\n *     HTTP/1.1 200 OK\n *\n * @apiUse UserNotFoundError\n */\n```\n\nIn this example, a block named `UserNotFoundError` is defined with `@apiDefine`.\nThat block could be used many times with `@apiUse UserNotFoundError`.\n\nIn the generated output, both methods `GET` and `PUT` will have the complete `UserNotFoundError` documentation.\n\nTo define an inherit block, use `apiDefine`.\nto reference a block, use `apiUse`. `apiGroup` and `apiPermission` are use commands to, but in their context the not inherit parameters, only title and description (in combination with apiVersion).\n\n**Inheritation only works with 1 parent**, more levels would make the inline code unreadable and changes really complex.\n\n## Versioning\n\nA useful feature provided by apiDoc is the ability to maintain the documentation for all previous versions and the latest version of the API. This makes it possible to compare a methods version with its predecessor. Frontend Developer can thus simply see what have changed and update their code accordingly.\n\n[View example output](example_versioning/)\n\nIn the example, click top right on select box (the main version) and select `Compare all with predecessor`.\n\n- The main navigation mark all changed methods with a green bar.\n- Each method show the actual difference compare to its predecessor.\n- Green marks contents that were added (in this case title text changed and field `registered` was added).\n- Red marks contents that were removed.\n\nYou can change the main version (top right) to a previous version and compare older methods with their predecessor.\n\n[apidoc.json](source/example_inherit/apidoc.json)\n\n```\n{\n  \"name\": \"example-versioning\",\n  \"version\": \"0.2.0\",\n  \"description\": \"apiDoc versioning example\"\n}\n```\n\nIn order to avoid code bloat when API documentation changes over time, it is recommended to use a separate history file named `_apidoc.js`. Before you change your documentation block, copy the old documentation to to this file, apiDoc will include the historical information automatically.\n\n[_apidoc.js](source/example_versioning/_apidoc.js)\n\n```\n/**\n * @api {get} /user/:id Get User information\n * @apiVersion 0.1.0\n * @apiName GetUser\n * @apiGroup User\n *\n * @apiParam {Number} id Users unique ID.\n *\n * @apiSuccess {String} firstname Firstname of the User.\n * @apiSuccess {String} lastname  Lastname of the User.\n *\n * @apiSuccessExample Success-Response:\n *     HTTP/1.1 200 OK\n *     {\n *       \"firstname\": \"John\",\n *       \"lastname\": \"Doe\"\n *     }\n *\n * @apiError UserNotFound The id of the User was not found.\n *\n * @apiErrorExample Error-Response:\n *     HTTP/1.1 404 Not Found\n *     {\n *       \"error\": \"UserNotFound\"\n *     }\n */\n```\n\n[example.js](source/example_versioning/example.js) (your current project file)\n\n```\n/**\n * @api {get} /user/:id Get User information and Date of Registration.\n * @apiVersion 0.2.0\n * @apiName GetUser\n * @apiGroup User\n *\n * @apiParam {Number} id Users unique ID.\n *\n * @apiSuccess {String} firstname  Firstname of the User.\n * @apiSuccess {String} lastname   Lastname of the User.\n * @apiSuccess {Date}   registered Date of Registration.\n *\n * @apiSuccessExample Success-Response:\n *     HTTP/1.1 200 OK\n *     {\n *       \"firstname\": \"John\",\n *       \"lastname\": \"Doe\"\n *     }\n *\n * @apiError UserNotFound The id of the User was not found.\n *\n * @apiErrorExample Error-Response:\n *     HTTP/1.1 404 Not Found\n *     {\n *       \"error\": \"UserNotFound\"\n *     }\n */\n```\n\nImportant is to set the version with `@apiVersion` on every documentation block.\n\nThe version can be used on every block, also on inherit blocks. You don't have to change the version on an inherit block, the parser check automatically for the nearest predecessor.\n\n## Full example\n\nThis is a complex example with `inherit`, `versioning` file and history file `_apidoc.js`, explanation is within code and generated documentation.\n\n[View example output](example/)\n\nFiles:\n\n- [_apidoc.js](source/example_full/_apidoc.js)\n- [example.js](source/example_full/example.js)\n- [apidoc.json](source/example_full/apidoc.json)\n\n# apiDoc-Params\n\nStructure parameter like:\n\n- `@apiDefine`\n\nis used to define a reusable documentation block. This block can be included in normal api documentation blocks. Using `@apiDefine` allows you to better organize complex documentation and avoid duplicating recurrent blocks.\n\nA defined block can have all params (like `@apiParam`), **except other defined blocks**.\n\n## @api\n\n```\n@api {method} path [title]\n```\n\n**Required!**\n\nWithout that indicator, apiDoc parser ignore the documentation block.\n\nThe only exception are documentation blocks defined by `@apiDefine`, they not required `@api`.\n\nUsage: `@api {get} /user/:id Users unique ID.`\n\n| Name          | Description                                                  |\n| ------------- | ------------------------------------------------------------ |\n| method        | Request method name: `DELETE`, `GET`, `POST`, `PUT`, ... More info [Wikipedia HTTP-Request_methods](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) |\n| path          | Request Path.                                                |\n| titleoptional | A short title. (used for navigation and article header)      |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n */\n```\n\n## @apiDefine\n\n```\n@apiDefine name [title]\n                     [description]\n```\n\nDefines a documentation block to be embedded within `@api` blocks or in an api function like `@apiPermission`.\n\n`@apiDefine` can only be used once per block\n\nBy using `@apiUse` a defined block will be imported, or with the name the title and description will be used.\n\nUsage: `@apiDefine MyError`\n\n| Name                | Description                                                  |\n| ------------------- | ------------------------------------------------------------ |\n| name                | Unique name for the block / value. Same name with different `@apiVersion` can be defined. |\n| titleoptional       | A short title. Only used for named functions like `@apiPermission` or `@apiParam (name)`. |\n| descriptionoptional | Detailed Description start at the next line, multiple lines can be used. Only used for named functions like `@apiPermission`. |\n\nExample:\n\n```\n/**\n * @apiDefine MyError\n * @apiError UserNotFound The \u003ccode\u003eid\u003c/code\u003e of the User was not found.\n */\n\n/**\n * @api {get} /user/:id\n * @apiUse MyError\n */\n```\n\n```\n/**\n * @apiDefine admin User access only\n * This optional description belong to to the group admin.\n */\n\n/**\n * @api {get} /user/:id\n * @apiPermission admin\n */\n```\n\nFor more details, see [inherit example](#example-inherit).\n\n## @apiDeprecated\n\n```\n@apiDeprecated [text]\n```\n\nMark an API Method as deprecated\n\nUsage: `@apiDeprecated use now (#Group:Name).`\n\n| Name | Description     |\n| ---- | --------------- |\n| text | Multiline text. |\n\nExample:\n\n```\n/**\n * @apiDeprecated\n */\n\n/**\n * @apiDeprecated use now (#Group:Name).\n *\n * Example: to set a link to the GetDetails method of your group User\n * write (#User:GetDetails)\n */\n```\n\n## @apiDescription\n\n```\n@apiDescription text\n```\n\nDetailed description of the API Method.\n\nUsage: `@apiDescription This is the Description.`\n\n| Name | Description                 |\n| ---- | --------------------------- |\n| text | Multiline description text. |\n\nExample:\n\n```\n/**\n * @apiDescription This is the Description.\n * It is multiline capable.\n *\n * Last line of Description.\n */\n```\n\n## @apiError\n\n```\n@apiError [(group)] [{type}] field [description]\n```\n\nError return Parameter.\n\nUsage: `@apiError UserNotFound`\n\n| Name                | Description                                                  |\n| ------------------- | ------------------------------------------------------------ |\n| (group)optional     | All parameters will be grouped by this name. Without a group, the default `Error 4xx` is set. You can set a title and description with [@apiDefine](#param-api-define). |\n| {type}optional      | Return type, e.g. `{Boolean}`, `{Number}`, `{String}`,`{Object}`, `{String[]}` (array of strings), ... |\n| field               | Return Identifier (returned error code).                     |\n| descriptionoptional | Description of the field.                                    |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiError UserNotFound The \u003ccode\u003eid\u003c/code\u003e of the User was not found.\n */\n```\n\n## @apiErrorExample\n\n```\n@apiErrorExample [{type}] [title]\n                 example\n```\n\nExample of an error return message, output as a pre-formatted code.\n\nUsage: `@apiErrorExample {json} Error-Response:                 This is an example.`\n\n| Name          | Description                           |\n| ------------- | ------------------------------------- |\n| typeoptional  | Response format.                      |\n| titleoptional | Short title for the example.          |\n| example       | Detailed example, multilines capable. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiErrorExample {json} Error-Response:\n *     HTTP/1.1 404 Not Found\n *     {\n *       \"error\": \"UserNotFound\"\n *     }\n */\n```\n\n## @apiExample\n\n```\n@apiExample [{type}] title\n            example\n```\n\nExample for usage of an API method. Output as a pre-formatted code.\n\nUse it for a complete example at the beginning of the description of an endpoint.\n\nUsage: `@apiExample {js} Example usage:            This is an example.`\n\n| Name         | Description                           |\n| ------------ | ------------------------------------- |\n| typeoptional | Code language.                        |\n| title        | Short title for the example.          |\n| example      | Detailed example, multilines capable. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiExample {curl} Example usage:\n *     curl -i http://localhost/user/4711\n */\n```\n\n## @apiGroup\n\n```\n@apiGroup name\n```\n\n**Should always be used.**\n\nDefines to which group the method documentation block belongs. Groups will be used for the Main-Navigation in the generated output. Structure definition not need `@apiGroup`.\n\nUsage: `@apiGroup User`\n\n| Name | Description                                       |\n| ---- | ------------------------------------------------- |\n| name | Name of the group. Also used as navigation title. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiGroup User\n */\n```\n\n## @apiHeader\n\n```\n@apiHeader [(group)] [{type}] [field=defaultValue] [description]\n```\n\nDescribe a parameter passed to you API-Header e.g. for Authorization.\n\nSimilar operation as [@apiParam](#param-api-param), only the output is above the parameters.\n\nUsage: `@apiHeader (MyHeaderGroup) {String} authorization Authorization value.`\n\n| Name                  | Description                                                  |\n| --------------------- | ------------------------------------------------------------ |\n| (group)optional       | All parameters will be grouped by this name. Without a group, the default `Parameter` is set. You can set a title and description with [@apiDefine](#param-api-define). |\n| {type}optional        | Parameter type, e.g. `{Boolean}`, `{Number}`, `{String}`,`{Object}`, `{String[]}` (array of strings), ... |\n| field                 | Variablename.                                                |\n| [field]               | Fieldname with brackets define the Variable as optional.     |\n| =defaultValueoptional | The parameters default value.                                |\n| descriptionoptional   | Description of the field.                                    |\n\nExamples:\n\n```\n/**\n * @api {get} /user/:id\n * @apiHeader {String} access-key Users unique access-key.\n */\n```\n\n## @apiHeaderExample\n\n```\n@apiHeaderExample [{type}] [title]\n                   example\n```\n\nParameter request example.\n\nUsage: `@apiHeaderExample {json} Request-Example:                 { \"content\": \"This is an example content\" }`\n\n| Name          | Description                           |\n| ------------- | ------------------------------------- |\n| typeoptional  | Request format.                       |\n| titleoptional | Short title for the example.          |\n| example       | Detailed example, multilines capable. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiHeaderExample {json} Header-Example:\n *     {\n *       \"Accept-Encoding\": \"Accept-Encoding: gzip, deflate\"\n *     }\n */\n```\n\n## @apiIgnore\n\n```\n@apiIgnore [hint]\n```\n\n**Place it on top of a block.**\n\nA block with `@apiIgnore` will not be parsed. It is usefull, if you leave outdated or not finished Methods in your source code and you don't want to publish it into the documentation.\n\nUsage: `@apiIgnore Not finished Method`\n\n| Name         | Description                                         |\n| ------------ | --------------------------------------------------- |\n| hintoptional | Short information why this block should be ignored. |\n\nExample:\n\n```\n/**\n * @apiIgnore Not finished Method\n * @api {get} /user/:id\n */\n```\n\n## @apiName\n\n```\n@apiName name\n```\n\n**Should always be used.**\n\nDefines the name of the method documentation block. Names will be used for the Sub-Navigation in the generated output. Structure definition not need `@apiName`.\n\nUsage: `@apiName GetUser`\n\n| Name | Description                                                  |\n| ---- | ------------------------------------------------------------ |\n| name | Unique name of the method. Same name with different `@apiVersion` can be defined. Format: *method* + *path* (e.g. Get + User), only a proposal, you can name as you want. Also used as navigation title. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiName GetUser\n */\n```\n\n## @apiParam\n\n```\n@apiParam [(group)] [{type}] [field=defaultValue] [description]\n```\n\nDescribe a parameter passed to you API-Method.\n\nUsage: `@apiParam (MyGroup) {Number} id Users unique ID.`\n\n| Name                         | Description                                                  |\n| ---------------------------- | ------------------------------------------------------------ |\n| (group)optional              | All parameters will be grouped by this name. Without a group, the default `Parameter` is set. You can set a title and description with [@apiDefine](#param-api-define). |\n| {type}optional               | Parameter type, e.g. `{Boolean}`, `{Number}`, `{String}`, `{Object}`, `{String[]}` (array of strings), ... |\n| {type{size}}optional         | Information about the size of the variable. `{string{..5}}` a string that has max 5 chars. `{string{2..5}}` a string that has min. 2 chars and max 5 chars. `{number{100-999}}` a number between 100 and 999. |\n| {type=allowedValues}optional | Information about allowed values of the variable. `{string=\"small\"}` a string that can only contain the word \"small\" (a constant). `{string=\"small\",\"huge\"}` a string that can contain the words \"small\" or \"huge\". `{number=1,2,3,99}` a number with allowed values of 1, 2, 3 and 99.  Can be combined with size: `{string {..5}=\"small\",\"huge\"}` a string that has max 5 chars and only contain the words \"small\" or \"huge\". |\n| field                        | Variablename.                                                |\n| [field]                      | Fieldname with brackets define the Variable as optional.     |\n| =defaultValueoptional        | The parameters default value.                                |\n| descriptionoptional          | Description of the field.                                    |\n\nExamples:\n\n```\n/**\n * @api {get} /user/:id\n * @apiParam {Number} id Users unique ID.\n */\n\n/**\n * @api {post} /user/\n * @apiParam {String} [firstname]  Optional Firstname of the User.\n * @apiParam {String} lastname     Mandatory Lastname.\n * @apiParam {String} country=\"DE\" Mandatory with default value \"DE\".\n * @apiParam {Number} [age=18]     Optional Age with default 18.\n *\n * @apiParam (Login) {String} pass Only logged in users can post this.\n *                                 In generated documentation a separate\n *                                 \"Login\" Block will be generated.\n */\n```\n\n## @apiParamExample\n\n```\n@apiParamExample [{type}] [title]\n                   example\n```\n\nParameter request example.\n\nUsage: `@apiParamExample {json} Request-Example:                 { \"content\": \"This is an example content\" }`\n\n| Name          | Description                           |\n| ------------- | ------------------------------------- |\n| typeoptional  | Request format.                       |\n| titleoptional | Short title for the example.          |\n| example       | Detailed example, multilines capable. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiParamExample {json} Request-Example:\n *     {\n *       \"id\": 4711\n *     }\n */\n```\n\n## @apiPermission\n\n```\n@apiPermission name\n```\n\nOutputs the permission name. If the name is defined with `@apiDefine` the generated documentation include the additional title and description.\n\nUsage: `@apiPermission admin`\n\n| Name | Description                    |\n| ---- | ------------------------------ |\n| name | Unique name of the permission. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiPermission none\n */\n```\n\n## @apiPrivate\n\n```\n@apiPrivate\n```\n\nDefines an API as being private to allow the creation of two API specification documents: one that excludes the private APIs and one that includes them.\n\nUsage: `@apiPrivate`\n\nCommand line usage to exclude/include private APIs: `--private false|true`\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiPrivate\n */\n```\n\n## @apiSampleRequest\n\n```\n@apiSampleRequest url\n```\n\nUse this parameter in conjunction with the apidoc.json configuration parameter [sampleUrl](#configuration-settings-sample-url).\n\nIf `sampleUrl` is set, all methods will have the api test form (the endpoint from [@api](#param-api) will be appended).\nWithout sampleUrl only methods with `@apiSampleRequest` will have a form.\n\nif `@apiSampleRequest url` is set in a method block, this url will be used for the request (it overrides sampleUrl when it starts with http).\n\nIf `sampleUrl` is set and you don't want a method with a test form, then add `@apiSampleRequest off` to the documentation block.\n\nUsage: `@apiSampleRequest http://test.github.com`\n\n| Name | Description                                                  |\n| ---- | ------------------------------------------------------------ |\n| url  | Url to your test api server.  Overwrite the configuration parameter sampleUrl and append [@api](#param-api) url: `@apiSampleRequest http://www.example.com`  Prefix the [@api](#param-api) url: `@apiSampleRequest /my_test_path`  Disable api test if configuration parameter sampleUrl is set: `@apiSampleRequest off` |\n\nExamples:\n\nThis will send the api request to **http://api.github.com/user/:id**\n\n```\nConfiguration parameter sampleUrl: \"http://api.github.com\"\n/**\n * @api {get} /user/:id\n */\n```\n\nThis will send the api request to **http://test.github.com/some_path/user/:id**\nIt overwrites sampleUrl.\n\n```\nConfiguration parameter sampleUrl: \"http://api.github.com\"\n/**\n * @api {get} /user/:id\n * @apiSampleRequest http://test.github.com/some_path/\n */\n```\n\nThis will send the api request to **http://api.github.com/test/user/:id**\nIt extends sampleUrl.\n\n```\nConfiguration parameter sampleUrl: \"http://api.github.com\"\n/**\n * @api {get} /user/:id\n * @apiSampleRequest /test\n */\n```\n\nThis will disable the api request for this api-method.\n\n```\nConfiguration parameter sampleUrl: \"http://api.github.com\"\n/**\n * @api {get} /user/:id\n * @apiSampleRequest off\n */\n```\n\nThis will send the api request to **http://api.github.com/some_path/user/:id**\nIt activates the request for this method only, because sampleUrl is not set.\n\n```\nConfiguration parameter sampleUrl is not set\n/**\n * @api {get} /user/:id\n * @apiSampleRequest http://api.github.com/some_path/\n */\n```\n\n## @apiSuccess\n\n```\n@apiSuccess [(group)] [{type}] field [description]\n```\n\nSuccess return Parameter.\n\nUsage: `@apiSuccess {String} firstname Firstname of the User.`\n\n| Name                | Description                                                  |\n| ------------------- | ------------------------------------------------------------ |\n| (group)optional     | All parameters will be grouped by this name. Without a group, the default `Success 200` is set. You can set a title and description with [@apiDefine](#param-api-define). |\n| {type}optional      | Return type, e.g. `{Boolean}`, `{Number}`, `{String}`,`{Object}`, `{String[]}` (array of strings), ... |\n| field               | Return Identifier (returned success code).                   |\n| descriptionoptional | Description of the field.                                    |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiSuccess {String} firstname Firstname of the User.\n * @apiSuccess {String} lastname  Lastname of the User.\n */\n```\n\nExample with `(group)`, more group-examples at [@apiSuccessTitle](#param-api-success-title):\n\n```\n/**\n * @api {get} /user/:id\n * @apiSuccess (200) {String} firstname Firstname of the User.\n * @apiSuccess (200) {String} lastname  Lastname of the User.\n */\n```\n\nExample with Object:\n\n```\n/**\n * @api {get} /user/:id\n * @apiSuccess {Boolean} active        Specify if the account is active.\n * @apiSuccess {Object}  profile       User profile information.\n * @apiSuccess {Number}  profile.age   Users age.\n * @apiSuccess {String}  profile.image Avatar-Image.\n */\n```\n\nExample with Array:\n\n```\n/**\n * @api {get} /users\n * @apiSuccess {Object[]} profiles       List of user profiles.\n * @apiSuccess {Number}   profiles.age   Users age.\n * @apiSuccess {String}   profiles.image Avatar-Image.\n */\n```\n\n## @apiSuccessExample\n\n```\n@apiSuccessExample [{type}] [title]\n                   example\n```\n\nExample of a success return message, output as a pre-formatted code.\n\nUsage: `@apiSuccessExample {json} Success-Response:                   { \"content\": \"This is an example content\" }`\n\n| Name          | Description                           |\n| ------------- | ------------------------------------- |\n| typeoptional  | Response format.                      |\n| titleoptional | Short title for the example.          |\n| example       | Detailed example, multilines capable. |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiSuccessExample {json} Success-Response:\n *     HTTP/1.1 200 OK\n *     {\n *       \"firstname\": \"John\",\n *       \"lastname\": \"Doe\"\n *     }\n */\n```\n\n## @apiUse\n\n```\n@apiUse name\n```\n\nInclude a with `@apiDefine` defined block. If used with `@apiVersion` the same or nearest predecessor will be included.\n\nUsage: `@apiUse MySuccess`\n\n| Name | Description                |\n| ---- | -------------------------- |\n| name | Name of the defined block. |\n\nExample:\n\n```\n/**\n * @apiDefine MySuccess\n * @apiSuccess {string} firstname The users firstname.\n * @apiSuccess {number} age The users age.\n */\n\n/**\n * @api {get} /user/:id\n * @apiUse MySuccess\n */\n```\n\n## @apiVersion\n\n```\n@apiVersion version\n```\n\nSet the version of an documentation block. Version can also be used in `@apiDefine`.\n\nBlocks with same group and name, but different versions can be compared in the generated output, so you or a frontend developer can retrace what changes in the API since the last version.\n\nUsage: `@apiVersion 1.6.2`\n\n| Name    | Description                                                  |\n| ------- | ------------------------------------------------------------ |\n| version | Simple versioning supported (major.minor.patch). More info on [Semantic Versioning Specification (SemVer)](http://semver.org/). |\n\nExample:\n\n```\n/**\n * @api {get} /user/:id\n * @apiVersion 1.6.2\n */\n```\n\nFor more watch [versioning example](#example-versioning).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flincanbin%2Fapidoc-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flincanbin%2Fapidoc-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flincanbin%2Fapidoc-markdown/lists"}