README

此骨架应用程序将在您的骨架项目中创建一个 openapi 应用程序。openapi 规范文件将根据代码（使用反射和 docblock）自动创建。将自动提供 SwaggerUI 界面，以便测试 API。

安装

通过 composer 安装

composer require tigron/skeleton-application-api

设置应用程序

您的 Openapi 应用程序应遵循以下目录结构

- App-directory from skeleton-core
  - Your app name
    - component
    - config
    - endpoint
    - exception (optional)
    - security (optional)

重要的是要理解，每个创建的类都应该位于正确的命名空间中。以下命名空间应被使用

component: \App\{APP_NAME}\Component
endpoint: \App\{APP_NAME}\Endpoint
exception: \App\{APP_NAME}\Exception
security: \App\{APP_NAME}\Security

配置

以下配置可以设置

事件

可以在应用程序执行过程中特定关键点执行任务的特定事件。此应用程序支持 skeleton-core 中描述的所有可用事件。此外，以下事件也是可用的

端点

端点将确定在 openapi 应用程序中创建的标签和路径。每个端点都需要扩展自 \Skeleton\Application\Api\Endpoint。让我们看看一个例子

<?php
namespace App\Openapi\Endpoint;

/**
 * Operations on users
 */
class User extends \Skeleton\Application\Api\Endpoint {

    /**
	 * Authenticate a user and initialise the session
	 *
	 * @access public
	 * @param string $username The username
	 * @param string $password The password
	 * @return string Login successful
	 */
	public function post_login($username, $password) {
		// Do your check here
		return "Login successful";
	}
}

此端点将在规范中创建一个包含 1 个路径的标签

POST /user?action=login

每个方法都应遵循以下命名规范

{HTTP_OPERATION}_{ACTION}({REQUIRED_PARAM1}, {REQUIRED_PARAM2})

在类中，docblock 数据用于

类定义的 docblock 将用作路径的描述
方法的 docblock 将用作标签的描述
方法的 docblock 将用于指定输入和输出参数、可能的异常以及需要使用的安全机制

参数

每个可以接受的参数都应该通过 "@param {TYPE} {NAME} {DESCRIPTION}" 定义。类型可以是原始数据类型（int、integer、boolean、float）或原始数据类型的数组。

数组的定义

@param string[] $names

返回变量

必须指定一个返回变量。此返回变量将用于成功的 HTTP 200 响应。返回变量可以是原始数据类型或组件。（有关更多信息，请参阅组件）。还支持原始数据类型的数组和组件的数组。

体

如果路径接受一个体，则应在 docblock 中声明

@body \App\Api\Component\Mybody $custom_body

body-class 是一个组件，需要实现特定于组件的方法。可以通过调用来检索体

$body = $this->get_body();

$body 变量将是 docblock 中定义的组件的实例。返回的对象将自动与组件中的组件属性进行验证。

异常

如果路径可以引起异常，则应在 docblock 中通过 @throws 定义。异常应该是 \Skeleton\Application\Api\Exception 或其扩展类。例如

@throws \Skeleton\Application\Api\Exception

安全

如果路径需要身份验证，则必须在 docblock 中指定

@security \Skeleton\Application\Api\Security

头部

如果路径将返回一个头部，则可以通过以下方式指定

@header X-My-Custom-Header

已弃用

如果路径已弃用，则可以通过以下方式指定

@deprecated

路由

为您的路径自动生成的 URL 不总是干净的 URL。一个包含路由信息的数组可以清理此 URL。例如

POST /user?action=edit&id={ID}

对于此 URL，可以在应用程序配置中创建一个 "routes" 配置项

'\App\Openapi\Endpoint\User' => [
	'/user/$action/$id',
],

通过定义此路由，URL 将重写为

POST /user/edit/{ID}

高级

端点中的所有路径都归入同一个标签。标签的名称会根据端点的classname自动生成。如果出于某种原因需要修改名称，可以通过以下方法实现：

/**
 * Overwrite automatic naming
 *
 * @access public
 * @return string $name
 */
public function _get_name() {
	return 'customName';
}

组件

组件相当于openapi模式。它们定义了可以在端点中复用的对象。组件应该实现以下接口：

\Skeleton\Application\Api\ComponentInterface

对于骨架对象，可以通过简单地使用特质来实现：

\Skeleton\Application\Api\Component

这个特质将实现以下可以覆盖的方法：

public function get_openapi_media_type(): \Skeleton\Application\Api\Media\Type;

返回对象的完整Media\Type对象。默认情况下，返回一个带有类型 'object' 和由get_openapi_component_properties返回的所有属性的媒体类型。

public function get_openapi_component_name(): string;

返回组件的友好名称。默认情况下，名称是从组件的classname中提取的。应用程序的命名空间被忽略。

public function get_openapi_component_properties(): array;

返回一个包含Media\Type对象的数组。数组的每个元素的键成为属性的名称。

public function get_openapi_additional_properties(): ?\Skeleton\Application\Api\Media\Type;

如果组件有可选属性，它们可以通过此方法返回。数组应与get_openapi_component_properties返回的结构相同：一个包含Media\Type对象的数组。

public function get_openapi_description(): string;

组件的描述。

public function get_openapi_example(): array;

组件的示例。

public function get_openapi_component_info(): array;

此方法返回实际对象，其正确语法由get_openapi_component_properties中描述。

骨架对象

如果你的组件类是从'\Skeleton\Object\Model'派生的对象，你可以使用已定义的特质：

\Skeleton\Application\Api\Component;

使用此特质，输出将匹配数据库中定义的完整对象。

媒体类型

要定义组件，需要返回一个媒体类型的数组。

整数

$media_type = new \Skeleton\Application\Api\Media\Type();
$media_type->type = 'integer';
$media_type->format = 'int64'; // Optional, possible values 'int32', 'int64'

数字

$media_type = new \Skeleton\Application\Api\Media\Type();
$media_type->type = 'number';
$media_type->format = 'float'; // Optional, possible values 'float', 'double'

字符串

$media_type = new \Skeleton\Application\Api\Media\Type();
$media_type->type = 'string';
$media_type->format = 'date'; // Optional, possible values 'date', 'date-time', 'password', 'byte', 'binary', 'uuid', ...

// Enums: To define an enum, add the 'enum' property
$media_type->enum = [ 'state1', 'state2' ];

对象

$media_type = new \Skeleton\Application\Api\Media\Type();
$media_type->type = 'object';
$media_type->value_type = '\App\Api\Component\ClassA';

数组

$media_type = new \Skeleton\Application\Api\Media\Type();
$media_type->type = 'array';

$value_type = new \Skeleton\Application\Api\Media\Type();
$value_type->type = 'object';
$value_type->value_type = '\App\Api\Component\MyObject';

$media_type->value_type = $value_type;

对象-文本

此媒体类型会自动将对象文本定义添加到openapi中。

$media_type = new \Skeleton\Application\Api\Media\Type\Object\Text();
$media_type->object = $my_object;
$media_type->field = 'name';
$properties['name'] = $media_type;

混合媒体类型

可以通过类\skeleton\application\api\media\type\mix()来描述混合媒体类型。

$media_type_mix = new \Skeleton\Application\Api\Media\Type\Mix();

$media_type1 = new \Skeleton\Application\Api\Media\Type();
$media_type1->type = 'object';
$media_type1->value_type = '\App\Api\Component\Class1';
$media_type_mix->add_media_type($media_type1);

$media_type2 = new \Skeleton\Application\Api\Media\Type();
$media_type2->type = 'object';
$media_type2->value_type = '\App\Api\Component\Class2';
$media_type_mix->add_media_type($media_type2);

$media_type3 = new \Skeleton\Application\Api\Media\Type();
$media_type3->type = 'object';
$media_type3->value_type = '\App\Api\Component\Class3';
$media_type_mix->add_media_type($media_type3);
$media_type_mix->criteria = 'anyOf'; // Possible values 'oneOf', 'allOf', 'anyOf'

额外属性

媒体类型可以有以下其他属性：

description: a description of the media type
required: boolean, indicates if the media type is required
nullable: boolean, can the value be null
readonly: only used in GET
writeonly: only used in POST/PUT

tigron / skeleton-application-api

维护者

详细信息