Lzh on GitHub

必须元素

OpenAPI 规范为有效的文档定义了最基本的信息集。

OpenAPI 规范为有效的文档定义了最基本的信息集。

大部分信息包括一些关于 API 的常规信息，如 name、version 以及至少一个端点。

端点反过来又需要一个路径和至少一个响应。

最低要求的注解

考虑到以上几点，一个带有单个端点的最小 API 可能看起来像这样：

<?php

use OpenApi\Attributes as OA;

#[OA\Info(title: 'My First API', version: '0.1')]
class OpenApi
{
}

class MyController
{
    #[OA\Get(path: '/api/data.json', operationId: 'getData')]
    #[OA\Response(response: '200', description: 'The data')]
    public function getResource()
    {
        // ...
    }
}

相应的 OpenAPI 文档结果如下：

openapi: 3.0.0
info:
  title: 'My First API'
  version: '0.1'
paths:
  /api/data.json:
    get:
      operationId: 236f26ae21b015a60adbce41f8f316e3
      responses:
        '200':
          description: 'The data'
代码位置
属性和注解可以添加到代码中声明的任何位置，具体由 PHP 文档定义。它们的范围受限于 PHP Reflection API 支持的范围。

可选元素

查看生成的文档，你会注意到 swagger-php 在某些元素缺失时会自动添加它们。

大部分情况下，这些元素是 @OA\OpenApi、@OA\Components 和 @OA\PathItem。