{"id":19694556,"url":"https://github.com/vaneves/apirus","last_synced_at":"2025-04-29T10:30:58.026Z","repository":{"id":45923209,"uuid":"264733964","full_name":"vaneves/apirus","owner":"vaneves","description":"📖 Apirus - Doc Generator","archived":false,"fork":false,"pushed_at":"2021-11-28T03:07:44.000Z","size":70,"stargazers_count":9,"open_issues_count":4,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-05T15:02:55.715Z","etag":null,"topics":["documentation-generator","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaneves.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":"2020-05-17T18:45:27.000Z","updated_at":"2024-08-17T14:24:20.000Z","dependencies_parsed_at":"2022-08-28T19:40:24.667Z","dependency_job_id":null,"html_url":"https://github.com/vaneves/apirus","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaneves%2Fapirus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaneves%2Fapirus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaneves%2Fapirus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaneves%2Fapirus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaneves","download_url":"https://codeload.github.com/vaneves/apirus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251483685,"owners_count":21596580,"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":["documentation-generator","php"],"created_at":"2024-11-11T19:23:30.549Z","updated_at":"2025-04-29T10:30:57.638Z","avatar_url":"https://github.com/vaneves.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apirus - Doc Generator\n\n![Apirus](https://user-images.githubusercontent.com/146581/82272220-50305680-9950-11ea-92d5-38cbe914d98f.png)\n\nPHP application to create beautiful rest API documentation using markdown. Inspired by [readme.com](https://readme.com/).\n\n## Installation\n\nTo install, run the command:\n\n```\ncomposer create-project --prefer-dist vaneves/apirus\n```\n\nAfter downloading, go to the application directory and copy the `.env.example` file as `.env`.\n\n```\ncp .env.example .env\n```\n\n## Building\n\nTo compile the HTML output, just run the following command:\n\n```\nphp apirus\n```\n\n### .env Configuration\n\nYou can configure settings to compile the API, to do so just edit the `.env` file and change the value of the variables.\n\n```\nAPI_URL=http://example.com/api\n\nSOURCE=\nDIST=\nTHEME=\nHIGHTLIGHT=\n```\n\n| Variable   | Description             | Default          |\n|------------|-------------------------|------------------|\n| API_URL    | Base URL of requests    |                  |\n| SOURCE     | Path the markdown files | ./docs           |\n| DIST       | Destination folder      | ./public         |\n| THEME      | Theme name              | ./themes/default |\n| HIGHTLIGHT | Highlight style         | dark             |\n\nThe `API_URL` variable is used to not repeat the complete URL of the request in all markdown files. You can use it `{{API_URL}}`, for example:\n\n````\n---\nurl: \"`{{API_URL}}/api/items\"\n---\n\n```request:cURL\ncurl --location --request GET '`{{API_URL}}/api/items' \\\n--header 'Content-Type: application/json' \n```\n````\n\n### Optional Arguments\n\nYou can enter arguments for changing the build. The accepted arguments are:\n\n| Argument  | Short | Description              | Default      |\n|-----------|-------|--------------------------|--------------|\n| help      |       | Prints a usage statement |              |\n| watch     |       | Watching files changes   |              |\n| src       | s     | Path the markdown files  | `SOURCE`     |\n| dist      | d     | Destination folder       | `DIST`       |\n| theme     | t     | Theme name               | `THEME`      |\n| highlight | h     | Highlight style          | `HIGHTLIGHT` |\n\nExample:\n\n```\nphp apirus --src my-docs --theme mytheme -h monokai\n```\n\n**If an argument is defined when compiling, it will overwrite the values defined in `.env`.**\n\n### Watching Files\n\nIn development environment you can use the `--watch` argument so that Apirus can see the directory where the markdown files are, as soon as there is a change (create, change or delete), it will automatically rebuild. For example:\n\n```\nphp apirus --watch\n```\n\nYou can pass other arguments as usual, for example:\n\n```\nphp apirus --src ../my-docs --theme ../mytheme --watch\n```\n\n## Creating Documentation\n\nBy default, the directory where the markdown files are located is in `docs`. But you can change. Within that directory you must create other directories, where each one will correspond to an item in the menu, for example:\n\n```\ndocs/\n├── 00 - Getting started\n|   ├── 00 - Description.md\n|   └── 01 - Another section.md\n└── 01 - Account\n    ├── 00 - Auth.md\n    ├── 01 - Register.md\n    └── 02 - Recover password.md\n```\n\nThe directory name will be used for the menu section title. But the numbering will be removed, as it is only used for ordering. For example `00 - Getting started` will generate the title` Getting started`.\n\nIn the directories you will create a file for each section. The file name is ignored if it has the `title` meta inside it. But if you don't have the `title` meta, the file name will be used in the menu. For example, `01 - Another section.md` will have the item in the` Another section` menu.\n\n### Meta\n\n\"Meta\" are used to build a section of your documentation. It is optional to inform the meta, but if defined, it must be of the following structure:\n\n```yaml\n---\ntitle: Get example\nmethod: GET\nurl: \"http://example.com/api/items\"\n---\n```\n\nAs I said, all are optional. If you leave the `title` blank, the file name without the format and initial numbering (used for sorting) will be used. If you leave the `method` or` url` blank, this information will not be rendered.\n\n**The \"meta\" must be entered at the beginning of the file.**\n\n### Requests\n\nYou can define several examples of requests, in several languages. It is somewhat similar to the code block, but we use the word `request` and in front of it the name of the language. For example:\n\n````\n```request:cURL\ncurl --location --request GET 'http://example.com/api/items' \\\n--header 'Content-Type: application/json' \n```\n````\n\n````\n```request:Python\nimport requests\nurl = \"http://example.com/api/items\"\nheaders = {\n  'Content-Type': 'application/json'\n}\nresponse = requests.request(\"GET\", url, headers=headers)\nprint(response.text.encode('utf8'))\n```\n````\n\nEach language block will be a tab with an example request on the interface. You can place a request block anywhere in the file.\n\n### Reponses\n\nYou can define examples of request responses. It is similar to a block of code, but this time you enter the HTTP code of the response. For example:\n\n````\n```response:200\n[{\n    \"id\": 1,\n    \"name\": \"example 1\"\n}, {\n    \"id\": 2,\n    \"name\": \"example 2\"\n}, {\n    \"id\": 3,\n    \"name\": \"example 3\"\n}]\n```\n````\n\n````\n```response:401\n{\n\t\"error\": \"Invalid token\"\n}\n```\n````\n\nEach block will be a tab with a response example. You can place a response block anywhere in the file.\n\n### Description\n\nAny information other than the meta, requisition block or return block, will be part of the section description. You can use any markdown markup as per the [Parsedown](https://github.com/erusev/parsedown) library.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaneves%2Fapirus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaneves%2Fapirus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaneves%2Fapirus/lists"}