README

Jot 是一个 Laravel 包，基于 PHPDoc 生成 Markdown 格式的 RESTful API 文档。

安装

使用 composer 安装 jot

composer require code-orange/jot

Laravel 5.5+

如果您使用 Laravel 5.5 或更高版本，该包将自动注册 Jot 提供器。

Laravel 5.4

将 CodeOrange\Jot\JotServiceProvider::class 添加到 config/app.php 中的 providers 数组。

配置

您可以使用 php artisan vendor:publish 命令将 jot 配置发布到您的应用

php artisan vendor:publish --provider=CodeOrange\\Jot\\JotServiceProvider

然后，更新 config/jot.php。

使用方法

生成文档

首先，使用 PHPDoc 记录您的控制器操作。

class MyController {
	/**
	 * Returns a value
	 *
	 * This method returns a cool value.
	 *
	 * @param mixed $b Some value
	 * @return JsonResponse {
	 *                          "a": 1,
	 *                          "b": "Example"
	 *                      }
	 */
	public function myAction(Request $r) {
		return response()->json([
			'a' => 1,
			'b' => $r->get('b')
		]);
	}
}

然后，运行 php artisan jot:generate。Markdown 格式的 API 文档将打印到您的控制台。

## Returns a value

This method returns a cool value.

`GET /example`

### Parameters

| Name | Located in | Description | Type |
| ---- | ---------- | ----------- | ---- |
|b|request|Some value|mixed|
|account|path|||

```json
{
    "a": 1,
    "b": "Example"
}
```

然后，您可以将此 Markdown 添加到您用于发布文档的任何工具中。这可以是 GitHub 上的 Markdown 文件、wiki 或自托管的文档站点。

该 Markdown 与 lord/slate 兼容，我们在 Odyssey 上使用它来发布我们的文档。

检查文档覆盖率

Jot 还可以检查您的所有公共 API 方法是否得到了适当的文档记录，例如作为 CI 测试流程的一部分。

php artisan jot:coverage

如果您的 API 中有未记录的方法，将退出并显示错误状态码。

可选地，您可以使用 --return 强制所有方法都有文档化的返回类型/示例。

动机

本项目深受 f2m2/apidocs 项目的影响。虽然该项目生成优秀的文档，但我不喜欢将 Laravel 应用自托管文档的想法（这可以通过静态方式完成，并且可能具有不同的访问模式）。

Jot 允许您分离 API 文档的生成和发布。

有关在 此博客文章 中构建 Jot 的更多信息。