README

此包旨在自动化 Swagger (Open Auth 3.0) 的 API 文档

发布配置

php artisan vendor:publish --provider="DigitSoft\Swagger\SwaggerGeneratorServiceProvider" --tag="config"

用法

要生成文档文件（YML），请运行以下命令

php artisan swagger:generate

要查看生成问题，请使用 diagnose 模式，此时不会生成文件，只会打印出有用的信息。

php artisan swagger:generate --diagnose

描述您的代码

注释列表

响应

只有当通过 @Annotation 明确记录时，才会解析响应。它必须放置在路由使用的 控制器方法 的 PHPDoc 中。原始响应

/**
 * Controller method PHPDoc
 *
 * @OA\Response(true,contentType="application/json",description="Boolean response")
 *
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */

JSON 原始响应

/**
 * Controller method PHPDoc
 *
 * @OA\ResponseJson({"key":"value"},status=201,description="User data response")
 *
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */

或

/**
 * Controller method PHPDoc
 *
 * @OA\ResponseJson({
 *      @OA\ResponseParam("key",type="string",example="value",description="Some parameter"),
 * },status=201,description="User data response")
 *
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */

来自类属性的响应

/**
 * Controller method PHPDoc
 *
 * @OA\ResponseClass("App\User",description="User model response")
 *
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */

在上面的例子中，响应数据将从 App\User PHPDoc 中解析。

1. @property 描述（属性名称、类型和描述）
2. @property-read 描述（如果设置了 with 属性在 ResponseClass 注解中）
3. @OA\Property 注解（属性名称、类型、描述、示例等。）

@OA\ResponseClass 用例，第一个是标准用法，但具有额外的属性

/**
 * @OA\ResponseClass("App\User",with={"profile"},status=201)
 */

作为项目列表

/**
 * @OA\ResponseClass("App\User",asList=true)
 */

作为分页项目列表

/**
 * @OA\ResponseClass("App\User",asPagedList=true)
 */

错误响应

/**
 * @OA\ResponseError(403) // Forbidden
 * @OA\ResponseError(404) // Not found
 * @OA\ResponseError(422) // Validation error
 */

请求体

请求数据是从用于路由和其注释（@OA\RequestBody、@OA\RequestBodyJson、@OA\RequestParam）的控制器方法的 FormRequest 类的 ::rules() 方法中解析的。我们可以从 ::rules() 方法中获取参数的名称和类型并建议一些示例，但如果您想完全描述请求体的参数，您必须在用于路由的控制器方法中为 FormRequest 类放置适当的注释。

示例

/**
 * @OA\RequestBodyJson({
 *   @OA\RequestParam("first_name",type="string",description="User name"),
 *   @OA\RequestParam("email",type="string",description="User email"),
 *   @OA\RequestParamArray("phones",items="string",description="User phones array"),
 * })
 */

标签

可以在路由使用的控制器类或方法中定义标签。不要在标签名称中使用空格 ，因为使用此标签名称的链接将在 Swagger UI 中断开，因此更好的想法是使用破折号 - 或下划线 _，或者甚至只是使用 CamelCased 标签名称。定义在控制器中的标签将应用于所有控制器方法。

/**
 * @OA\Tag("Tag-name")
 */

受保护

此注释用于标记路由为 受保护，并告诉 Swagger，必须提供有效的用户凭据才能访问此路由。将其放置在控制器方法中。

/**
 * @OA\Secured()
 */

属性

@OA\Property 注解用于描述类属性，作为 PHPDoc 中 @property 的替代或补充。您可以放置属性的示例（如果属性是关联数组，例如）或完全描述属性，如果您不想为其放置 @property 声明。

/**
 * @OA\Property("notification_settings",type="object",example={"marketing":false,"user_actions":true},description="User notification settings")
 */

PropertyIgnore

@OA\PropertyIgnore 注解用于从对象描述中删除指定的属性。

/**
 * @OA\PropertyIgnore("property_name")
 */

符号链接

此注释可以用于描述指向另一个类的符号链接（例如，用于响应）。在出现该注释的类的 PHPDoc 中的所有数据都将被忽略。

您必须使用完整命名空间注释，例如 OA\Property。

此外，您可以在代码示例中导入命名空间以获得更好的代码完成。

namespace App\Models;

use OA;

/**
 * Test model class
 *
 * @OA\Property("id",type="integer",description="Primary key")
 *
 * @property string $name String name
 */
class TestModel {}

更多

存在抽象注释类 OA\DescriptionExtender，您可以使用它来创建自己的注释，这些注释必须向路由描述添加一些信息。

以下是一个示例。

<?php

namespace App\Components\Annotations\Swagger;

use OA\DescriptionExtender;
use Doctrine\Common\Annotations\Annotation;
use Doctrine\Common\Annotations\Annotation\{Attribute, Attributes};

/**
 * Describes needed permission
 * @Annotation
 * @Attributes({
 *  @Attribute("value",type="string"),
 * })
 * @package App\Components\Annotations\Swagger
 */
class Permission extends DescriptionExtender
{
    /**
     * @inheritdoc
     */
    public function __toString()
    {
        return '**Permission:** `' . $this->value . '`';
    }
}

您可以使用示例中的注释

<?php
use App\Components\Annotations\Swagger as SWA;


/**
 * Controller method PHPDoc
 *
 * @OA\ResponseClass("App\User",description="User model response")
 * @SWA\Permission("articles.can-update")
 *
 * @param Request $request
 * @return \Illuminate\Http\JsonResponse
 */

它将向路由描述添加以下文本

Description for route goes here...bla-bla-bla...

**Permission:** `articles.can-update`