README

有句话这么说，当轮子已经造好，为什么还要花时间再造一个同样的轮子？对此，由于我很好奇，我想了解那个轮子的详细情况，并自己构建其结构。

你一定在各个网站和目录中见过api-doc包，api-doc是为开发者和程序员设计的一套指令和技术指南。这份文档提供了有关如何使用应用程序编程接口（API）的信息，包括如何发送请求、参数以及服务如何响应。api-doc文档旨在帮助开发者正确使用服务或平台，提高开发者和API提供者之间的理解，并提高应用开发的效率和质量。

特性

能够为特定地址创建文档
在文档中发送请求并显示输出
能够定义认证信息和访问级别
能够定义和编辑模拟代码

安装

安装包

composer require a.sharifnezhad/api-doc

运行以下命令发布配置文件

php artisan vendor:publish --tag=apidoc-config

这将创建一个api-doc.php文件在您的配置文件夹中。

默认情况下，文档输出保存在并更新在storage/app/public目录。由于这个目录在Laravel中默认不是公开的，您需要运行以下命令来访问它。
```
php artisan storage:link
```

配置

如果您想更改模拟代码或添加另一种新语言，请按照以下步骤操作
```
code_sample => [
    is_enable => true,
    'directory' => '',
    'language-tabs' => [
        'bash' => 'Bash',
        'javascript' => 'Javascript',
        'php' => 'PHP',
        ]
]
```
- 如果您想使此部分在文档中显示或不显示，请在apidoc配置文件中禁用is_enable => true。
- 如果您添加了新语言，您必须添加在视图目录中创建的文件名以及language-tabs部分中所需的名称。
- 如果您将模拟代码放在特定的目录中，除了运行以下命令
```
php artisan vendor:publish --tag=apidoc-code-sample
```
  执行上述命令后，将在resources/views目录中创建一个名为CodeSamples的目录。目录添加后，必须将目录名添加到directory部分，这里写为'directory' => 'CodeSamples'。

如何添加微服务认证信息如下：要添加认证信息，您可以在security部分中添加所有内容，以下我将给出一些示例，供您参考以开始您的学习。

Bearer令牌

'BearerAuth' => [
    'type' => 'http',
    'scheme' => 'bearer',
    'bearerFormat' => 'JWT',
    'in' => 'header'
],

oauth2

"oauth2" => [
    "type" => "oauth2",
    "flows" => [
        "implicit" => [
            "authorizationUrl" => "https=>//example.com/oauth/authorize",
            "scopes" => [
                "read" => "Grants read access to resources",
                "write" => "Grants write access to resources",
                "admin" => "Grants administrative access to resources"
            ],
        ],
    ],
],

API密钥

"apiKey" => [
    "type" => "apiKey",
    "name" => "X-API-Key",
    "in" => "header"
],

基本认证

"basicAuth" => [
    "type" => "http",
    "scheme" => "basic"
],

如果您想从根目录写入文档属性，只需写其端点名称如下
```
'routes' => [
    'prefixes' => [
        'api/'
    ],
],
```

如果您想使所有路由都包含文档，应将api/替换为*

用法

php artisan apidoc:generate

记录您的API

此包使用以下资源生成API文档

分组端点

此包使用HTTP控制器doc块创建目录表和显示API方法的描述。

在控制器文档块中使用@group可以在API文档中创建一个分组。该控制器处理的所有路由都将在此分组下在侧边栏中分组。在@group之后的简短描述应该是唯一的，以便锚点标签可以导航到此部分。可以在下面包含一个更长的描述。

注意：使用@group是可选的。未分组的路由将被放置在general分组中。

指定请求参数

要指定API路由接受的参数列表，请使用@bodyParam和@pathParam注解。

@bodyParam注解接受参数的名称
@pathParam注解接受参数的名称

/**
 * @group Items
 */
class GetPostController extends Controller
{
    /**
     * Store2121 item
     *
     * Add a new item to the items collection.
     * @bodyParam {
     *      "key":"name",
     *       "type":"string",
     *        "description":"The name of the item. Example: Samsung Galaxy s10",
     *         "example":"Samsung Galaxy s10"
     * }
     * @bodyParam {
     *      "key":"name2",
     *       "type":"string",
     *       "required":true,
     *        "description":"The name of the item. Example: Samsung Galaxy s10",
     *         "example":"Samsung Galaxy s10"
     * }
     * @response {
     *      "status": 302,
     *      "success": true,
     *      "data": {
     *          "id": 10,
     *          "price": 100.00,
     *          "name": "Samsung Galaxy s10"
     *      }
     * }
     **/
    public function test()
    {

    }
}

指示认证状态

您可以在方法上使用@authenticated注解来指示端点是否经过认证。将提供一个用于认证令牌的字段，并在交互式文档中将其标记为必需。

许可证

MIT

a.sharifnezhad / api-doc

维护者

详细信息

README

特性

安装

配置

用法

记录您的API

分组端点

指定请求参数

指示认证状态

许可证