README

PHP应用程序，用于使用Markdown创建美观的REST API文档。灵感来源于 readme.com。

安装

要安装，请运行以下命令

composer create-project --prefer-dist vaneves/apirus

下载后，进入应用程序目录，将.env.example文件复制为.env。

cp .env.example .env

构建

要编译HTML输出，只需运行以下命令

php apirus

.env配置

您可以通过编辑.env文件并更改变量的值来配置设置以编译API。

API_URL=http://example.com/api

SOURCE=
DIST=
THEME=
HIGHTLIGHT=

API_URL变量用于不在所有Markdown文件中重复请求的完整URL。您可以使用它{{API_URL}}，例如

---
url: "`{{API_URL}}/api/items"
---

```request:cURL
curl --location --request GET '`{{API_URL}}/api/items' \
--header 'Content-Type: application/json' 
```

可选参数

您可以为更改构建输入参数。接受的参数有

示例

php apirus --src my-docs --theme mytheme -h monokai

当编译时定义参数，它将覆盖在.env中定义的值。

监视文件

在开发环境中，您可以使用--watch参数，以便Apirus可以监视Markdown文件的目录，一旦发生更改（创建、更改或删除），它将自动重新构建。例如

php apirus --watch

您可以像通常一样传递其他参数，例如

php apirus --src ../my-docs --theme ../mytheme --watch

创建文档

默认情况下，Markdown文件所在的目录是docs。但您可以更改。在目录中，您必须创建其他目录，每个目录将对应于菜单中的一个项，例如

docs/
├── 00 - Getting started
|   ├── 00 - Description.md
|   └── 01 - Another section.md
└── 01 - Account
    ├── 00 - Auth.md
    ├── 01 - Register.md
    └── 02 - Recover password.md

目录名将用于菜单部分标题。但编号将被移除，因为它仅用于排序。例如00 - 入门将生成标题入门。

在您创建的目录中，您将为每个部分创建一个文件。文件名被忽略，如果它包含title元信息。但如果没有title元信息，则文件名将用于菜单。例如，01 - 另一个部分.md将在另一个部分菜单中创建一个项。

元信息

"元信息"用于构建文档的一部分。通知元信息是可选的，但如果已定义，则必须具有以下结构

---
title: Get example
method: GET
url: "http://example.com/api/items"
---

正如我所说的，所有这些都是可选的。如果您留空title，则将使用不带格式和初始编号（用于排序）的文件名。如果您留空method或url，则不会渲染此信息。

"meta"必须在文件开头输入。

请求

您可以在多种语言中定义多个请求示例。它与代码块类似，但我们使用“请求”一词，并在其前面加上语言名称。例如

```request:cURL
curl --location --request GET 'http://example.com/api/items' \
--header 'Content-Type: application/json' 
```

```request:Python
import requests
url = "http://example.com/api/items"
headers = {
  'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers)
print(response.text.encode('utf8'))
```

每个语言块将是一个带有示例请求的选项卡。您可以在文件中的任何位置放置请求块。

响应

您可以定义请求响应的示例。它与代码块类似，但这次您输入响应的HTTP代码。例如

```response:200
[{
    "id": 1,
    "name": "example 1"
}, {
    "id": 2,
    "name": "example 2"
}, {
    "id": 3,
    "name": "example 3"
}]
```

```response:401
{
	"error": "Invalid token"
}
```

每个块将是一个带有响应示例的选项卡。您可以在文件中的任何位置放置响应块。

描述

除元信息、请求块或返回块之外的所有信息都将作为部分描述的一部分。您可以使用Parsedown库中的任何Markdown标记。