README

读取和写入OpenAPI 3.x YAML和JSON文件，并将内容转换为PHP对象。

它还提供了一个CLI工具，用于验证和转换OpenAPI 3.x描述文件。

支持的OpenAPI版本

3.0.x
3.1.x

安装

composer require php-openapi/openapi

使用

此库提供了一种用于读取和写入OpenAPI文件的底层API。它被用于高级工具以执行出色的工作

由原始 cebe/php-openapi 使用
- cebe/yii2-openapi REST API从OpenAPI 3描述的代码生成器，包括假数据生成器。
- cebe/yii2-app-api 是用于开发API优先应用程序的Yii框架应用程序模板。
- league/openapi-psr7-validator 验证PSR-7消息（HTTP请求/响应）是否与OpenAPI描述相匹配。
- dsuurlant/response2schema 基于示例数据生成OpenAPI模式的一个快速简单的工具。
... (添加您的)

用法

CLI工具

$ vendor/bin/php-openapi help
PHP OpenAPI 3 tool
------------------
by Carsten Brandt <mail@cebe.cc>

Usage:
  php-openapi <command> [<options>] [input.yml|input.json] [output.yml|output.json]

  The following commands are available:

    validate   Validate the API Description in the specified input file against the OpenAPI v3.0 schema.
               Note: the validation is performed in two steps. The results are composed of
                (1) structural errors found while reading the API Description file, and
                (2) violations of the OpenAPI v3.0 schema.

               If no input file is specified input will be read from STDIN.
               The tool will try to auto-detect the content type of the input, but may fail
               to do so. You may specify --read-yaml or --read-json to force the file type.

               Exits with code 2 on validation errors, 1 on other errors and 0 on success.

    convert    Convert a JSON or YAML input file to JSON or YAML output file.

               If no input file is specified input will be read from STDIN.
               If no output file is specified output will be written to STDOUT.
               The tool will try to auto-detect the content type of the input and output file, but may fail
               to do so. You may specify --read-yaml or --read-json to force the input file type.
               and --write-yaml or --write-json to force the output file type.

               By default all references are resolved (replaced with the object referred to). You can control
               handling of references with the following arguments:

               --resolve-none      Do not resolve references.
               --resolve-external  Only resolve references that point to external files.
                                   This process is often referred to as "inlining".
               --resolve-all       Resolve all references (default).
                                   Recursive pointers will stay references.

    inline     Convert a JSON or YAML input file to JSON or YAML output file and
               resolve all external references. The output will be a single API Description file.
               This is a shortcut for calling convert --resolve-external.

    help       Shows this usage information.

  Options:

    --read-json   force reading input as JSON. Auto-detect if not specified.
    --read-yaml   force reading input as YAML. Auto-detect if not specified.
    --write-json  force writing output as JSON. Auto-detect if not specified.
    --write-yaml  force writing output as YAML. Auto-detect if not specified.
    -s, --silent  silent mode. Will hide all success/information messages and only print errors.

读取API描述文件

从JSON文件读取OpenAPI描述

use openapiphp\openapi\Reader;

// realpath is needed for resolving references with relative Paths or URLs
$openapi = Reader::readFromJsonFile(realpath('openapi.json'));

从YAML读取OpenAPI描述

use openapiphp\openapi\Reader;

// realpath is needed for resolving references with relative Paths or URLs
$openapi = Reader::readFromYamlFile(realpath('openapi.yaml'));
// you may also specify the URL to your API Description file
$openapi = Reader::readFromYamlFile('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml');

访问API描述数据

echo $openapi->openapi; // openAPI version, e.g. 3.0.0
echo $openapi->info->title; // API title
foreach($openapi->paths as $path => $definition) {
    // iterate path definitions
}

对象属性与OpenAPI规范中完全一致。您还可以访问由规范扩展添加的附加属性。

写入API描述文件

use openapiphp\openapi\spec\OpenApi;
use openapiphp\openapi\spec\PathItem;

// create base API Description
$openapi = new OpenApi([
    'openapi' => '3.0.2',
    'info' => [
        'title' => 'Test API',
        'version' => '1.0.0',
    ],
    'paths' => [],
]);
// manipulate description as needed
$openapi->paths['/test'] = new PathItem([
    'description' => 'something'
]);
// ...

$json = \openapiphp\openapi\Writer::writeToJson($openapi);

生成以下JSON数据

{
    "openapi": "3.0.0",
    "info": {
        "title": "Test API",
        "version": "1.0.0"
    },
    "paths": {
        "/test": {
            "description": "something"
        }
    }
}

使用准备好的对象写入API描述文件

从版本1.2.0开始，上述示例也可以这样编写（传递对象而不是数组）

use openapiphp\openapi\spec\OpenApi;
use openapiphp\openapi\spec\PathItem;
use openapiphp\openapi\spec\Info;


// create base API Description
$openapi = new OpenApi([
    'openapi' => '3.0.2',
    'info' => new Info([
        'title' => 'Test API',
        'version' => '1.0.0',
    ]),
    'paths' => [
        '/test' => new PathItem([
            'description' => 'something'
        ]),
    ],
]);
$json = \openapiphp\openapi\Writer::writeToJson($openapi);

读取API描述文件并解析引用

在上面的示例中，我们已将原始JSON或YAML数据传递给Reader。为了能够解析对外部文件中结构的引用，我们必须提供完整的上下文。

use openapiphp\openapi\Reader;
use openapiphp\openapi\spec\OpenAPI;
use openapiphp\openapi\ReferenceContext;

// there are two different modes for resolving references:
// ALL: resolve all references, which will result in a large description with a lot of repetition
// but no references (except if there are recursive references, these will stop at some level)
$mode = ReferenceContext::RESOLVE_MODE_ALL;
// INLINE: only references to external files are resolved, references to places in the current file
// are still Reference objects.
$mode = ReferenceContext::RESOLVE_MODE_INLINE;

// an absolute URL or file path is needed to allow resolving external references
$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json', OpenAPI::class, $mode);
$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml', OpenAPI::class, $mode);

如果数据已通过不同的方式加载，则可以通过提供上下文手动解析引用，如下所示

$openapi->resolveReferences(
    new \openapiphp\openapi\ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml')
);

验证

该库提供了简单的验证操作，用于检查基本的OpenAPI规范要求。这与CLI工具中“在读取API描述文件时发现的结构错误”相同。此验证不包括与OpenAPI v3.0/v3.1 JSON模式进行检查，这仅在CLI中实现。

// return `true` in case no errors have been found, `false` in case of errors.
$specValid = $openapi->validate();
// after validation getErrors() can be used to retrieve the list of errors found.
$errors = $openapi->getErrors();

注意：验证在非常基础的级别上进行，并且并不完整。因此，失败的验证将显示一些错误，但给出的错误列表可能不完整。此外，通过验证并不一定意味着规范是完全有效的。

开发

您可以使用docker环境进行本地开发

# Build once the container
docker build -t php-openapi .
# Run commands in the container 
docker run -it -v `pwd`:/var/www -w /var/www php-openapi sh

php-openapi / openapi

维护者

详细信息