README

使用OpenAPI规范生成器，您可以以面向对象的方式为您自己的REST API创建一个OpenAPI（或Swagger）规范。

使用Composer安装

运行以下命令将包添加到您的项目的composer.json中

$ composer require connectholland/openapi-specification-generator

使用方法

在开始自己的API规范之前，建议先阅读OpenAPI规范，这样您将对规范中的不同项目有一个整体的理解。

所有必需的OpenAPI属性都作为构造函数参数添加，因此您不会不小心忘记它们并生成无效的规范。

基本用法

以下是最小可能的规范示例。

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('My awesome API', '1.0.0');

$specification = Specification::create($info);

要将Specification实例转换为JSON规范，可以将实例插入到json_encode中。

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('My awesome API', '1.0.0');

$specification = Specification::create($info);

echo json_encode($specification, JSON_PRETTY_PRINT);

上述代码将生成以下有效的JSON API规范。

{
    "swagger": "2.0",
    "info": {
        "title": "My awesome API",
        "version": "1.0.0"
    },
    "paths": {}
}

虽然上述API规范是有效的，但它不是很实用，因为它不包含API端点。因此，让我们尝试一个实际的示例。

Echo API示例

Echo API示例可在Swagger编辑器中找到。以下代码展示了如何生成此示例。

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Parameter\FormDataParameter;
use ConnectHolland\OpenAPISpecificationGenerator\Parameter\PathParameter;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Operation;
use ConnectHolland\OpenAPISpecificationGenerator\Path\PathItem;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Response\Response;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Responses;
use ConnectHolland\OpenAPISpecificationGenerator\Schema\Primitive\StringElement;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('Echo', '1.0.0')
    ->setDescription("#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n");

$specification = Specification::create($info)
    ->setHost('mazimi-prod.apigee.net')
    ->setSchemes(array('http'))
    ->setBasePath('/echo');

$specification->setPath('/', PathItem::create()
    ->setGet(
        Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo GET'))
        )
    )
    ->setPost(
        Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo POST'))
        )
        ->addParameter(
            FormDataParameter::create('name', StringElement::create())
                ->setDescription('name')
        )
        ->addParameter(
            FormDataParameter::create('year', StringElement::create())
                ->setDescription('year')
        )
    )
);

$specification->setPath('/test-path/{id}', PathItem::create()
    ->setGet(Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo test-path'))
        )
    )
    ->setParameters(
        array(
            PathParameter::create('id', StringElement::create())->setDescription('ID'),
        )
    )
);

echo json_encode($specification, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

生成的API规范可在此处找到：这里。

更多示例可以在Specification测试类中找到。

致谢

此包由Niels Nijens编写和维护。

还可以查看参与此项目的贡献者列表。

许可证

此包根据MIT许可证授权。有关详细信息，请参阅LICENSE文件。