README

此包包含使用 doctrine 注解生成 RESTful API 交互式 OpenApi 文档的基本功能。

它包含一个控制器，用于渲染 Swagger UI，并通过基于项目文件中 OpenApi 注解生成的 json 文件获取其输入。

它使用了 sintbert/swagger-php 包。

调用文档

后端

存在一个可由管理员访问的后端模块，用于渲染 Swagger UI。

前端

要调用前端中的文档，您需要在后端作为管理员登录。然后您可以调用 API

{PROJECT_BASE_URI}/neos/api/documentation.html

要访问仅用于填充 Swagger UI 的生成的 json 文件，可以直接调用 json 文件

{PROJECT_BASE_URI}/neos/api/documentation.json

编写文档

要考虑的文档文件

有指定需要考虑生成文档的文件夹（s）的可能性。默认设置为

FLOW_PATH_ROOT/LocalPackages

要更改此设置，只需更改设置

Avency:
  Neos:
    OpenApi:
      scanPath: {NEW_PATH}

导入语句

所有添加了文档注解的文件都需要使用以下语句

use OpenApi\Annotations as OA;

注解

信息

需要添加到单独的文件中，并包含有关 api 的一般信息，例如

/**
 * @OA\Info(
 *   version="0.1.0",
 *   title="Portal Api",
 *   description="This is a the documentation for the API which is used in the admin panel."
 * )
 */

标签

标签用作不同 api 端点可以分组在一起的一组。

它应该在不同的控制器顶部定义。

可以在不同的操作中引用该标签。

/**
 * @OA\Tag(
 *   name="portal user",
 *   description="Everything about frontend portal users"
 * )
 */

操作

有不同类型的操作可用于描述不同的 api 端点，如 @OA\Get、@OA\Post、@OA\Put 或 @OA\Delete。

它们应该在方法描述中各自定义。

它们包含一个 path、一个简短的 summary 和一个 description。如果 url 接受参数，可以添加 @OA\Parameters。 @OA\Response 定义了不同的响应代码。

/**
 *  @OA\Get(
 *    path="/api/v1/portaluser",
 *    summary="Find portal user by identifier",
 *    description="Returns user data for the given DB identifier or the specific value for a property",
 *    tags={"portal user"},
 *    @OA\Parameter(
 *      name="identifier",
 *      in="query",
 *      description="Identifier of user object",
 *      required=true,
 *      @OA\Schema(
 *        type="string",
 *        @OA\Items(type="string"),
 *      )
 *    ),
 *    @OA\Response(
 *      response=200,
 *      description="successful operation, returns user data",
 *      @OA\JsonContent(
 *        ref="#/components/schemas/User",
 *        type="object",
 *        @OA\Items(ref="#/components/schemas/User")
 *      ),
 *    ),
 *    @OA\Response(
 *      response="500",
 *      description="error - identifier was not passed as string, any portal user found by identifier",
 *    )
 *  )
 */

模式

模式描述了一个模型的表示。

应在域模型上添加注解。 schema-属性由类名采用，但可以覆盖或设置，如果在外部域模型之外定义了特殊模式。

它们包含一个 title 和一个简短的 description。如果需要，可以定义特殊的 @OA\Property 值，如果模式应代表比在类中定义的变量更多的内容，例如标识符。

/**
 * @OA\Schema(
 *   schema="User",
 *   title="User model",
 *   description="User model with all user related data",
 *   @OA\Xml(
 *     name="User"
 *   ),
 *   @OA\Property(
 *     property="identifier",
 *     description="db-identifier",
 *     title="identifier",
 *     example="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
 *     type="string"
 *   )
 * )
 */

属性

属性描述模型中的单个属性。应在属性附近添加注解。

关于类型的某些信息不需要显式定义，但可以来自属性的类型。

/**
 * @OA\Property(
 *     description="Last Name",
 *     title="Last Name",
 *     example="Mustermann"
 * )
 *
 * @var string
 * @ORM\Column(nullable=TRUE)
 */
protected $lastName;

也可以引用其他 Schema 对象。如果此类型存在其他模式，将也会由属性类型检测到。

/**
 * @OA\Property(
 *     description="Address",
 *     title="Address"
 * )
 *
 * @ORM\OneToOne(cascade={"persist", "remove"})
 * @ORM\Column(nullable=TRUE)
 * @var Address
 */
protected $defaultAddress;

也可以手动添加引用。

@OA\Items(ref="#/components/schemas/Address")

更多信息

其他参数或注解可用。更多信息可以在 OpenAPI 规范网站上找到

https://swagger.org.cn/specification/

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件