README

基于 OpenAPI 规范的 PHP 轻量级 OpenAPI 解析库，允许开发者轻松提取模式数据。

如何安装？

$ composer require nass59/apollo-openapi

你可以用它做什么？

获取路径

在 OpenAPI 术语中，路径是端点（资源），例如 /users 或 /reports/summary/，这些是您的 API 暴露的内容。

所有路径都相对于 API 服务器 URL。

$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPaths();
/*
 * [
 *   '/articles',
 *   '/articles/{id}',
 *   '/images',
 *   ...
 * ]
 */

带有操作的获取路径

在 OpenAPI 术语中，路径是端点（资源），例如 /users 或 /reports/summary/，这些是您的 API 暴露的内容。

操作是用于操作这些路径的 HTTP 方法，例如 GET、POST 或 DELETE。

$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPathsWithOperations();
/*
 * [
 *   '/articles' => [
 *     'get' => [...],
 *     'post' => [...],
 *   ],
 *   '/articles/{id}' => [
 *     'get' => [...],
 *   ],
 *   ...
 * ]
 */

带有操作的获取路径

获取特定的路径（即端点）并返回其操作。

$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getPathWithOperations('/articles');
/*
 * [
 *   'get' => [...],
 *   'post' => [...],
 * ]
 */

获取请求体

请求体通常包含要创建的资源表示。

OpenAPI 3.0 提供了 requestBody 关键字来描述请求体。

默认情况下，请求体是可选的。

$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$operations = $openAPI->getPathWithOperations('/articles');
$openAPI->getRequestBody($operations['post']);
/*
 * [
 *   '$ref' => '#/components/requestBodies/ArticleBody',
 * ]
 */

获取定义

OpenAPI 3.0 数据类型基于扩展的 JSON Schema 规范 Draft 00 子集。

数据类型使用 Schema 对象进行描述。

$openAPI = new OpenAPI('config/schemas/', 'apollo.yaml');
$openAPI->getDefinition('/articles', 'postArticle');
/*
 * [
 *   'type' => 'object',
 *   'required' => ['name', 'headline'],
 *   'additionalProperties' => false,
 *   'properties' => [
 *     'name' => ['type' => 'string'],
 *     'headline' => ['type' => 'string'],
 *     ...
 *   ]
 * ]
 */

Schema 示例

openapi: 3.0.0

servers:
  - url: 'https://api.apollo.dev:8091/'

info:
  version: "v1-oas3"
  title: Apollo API
  description: Share images and videos with your friends.
  termsOfService: terms
  license:
    name: MIT
    url: https://open-source.org.cn/licenses/MIT

tags:
  - name: article
    description: Everything about articles

paths:
  /articles:
    get:
      tags:
        - article
      operationId: getArticles
      summary: ''
      description: Get a list of articles
      parameters:
        - name: fields[articles]
          in: query
          description: List of fields to display separated by a comma.
          example: "name,headline"
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: Field use to sort the result.
          example: "-name"
          required: false
          schema:
            type: string
        - name: page[offset]
          in: query
          description: Number of page to skip.
          required: false
          schema:
            type: integer
            default: 1
        - name: page[limit]
          in: query
          description: The numbers of items to return.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Collection'
    post:
      tags:
        - article
      operationId: postArticle
      summary: ''
      description: Create a new article
      responses:
        '201':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: Bad request
      requestBody:
        $ref: '#/components/requestBodies/ArticleBody'

  /articles/{id}:
    get:
      tags:
        - article
      operationId: getArticle
      summary: ''
      description: Get a specific article
      parameters:
        - name: id
          in: path
          description: The id of the article
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '404':
          description: Article not found
    put:
      tags:
        - article
      summary: ''
      description: Update an existing article
      operationId: putArticle
      parameters:
        - name: id
          in: path
          description: The id of the article
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: Bad request
        '404':
          description: Article not found
      requestBody:
        $ref: '#/components/requestBodies/ArticleBody'
    delete:
      tags:
        - article
      summary: ''
      description: Delete a specific article
      operationId: deleteArticle
      parameters:
        - name: id
          in: path
          description: The id of the article
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Article deleted
        '404':
          description: Article not found
          
components:
  schemas:
    ArticleBody:
      type: object
      required:
        - name
        - headline
        - article_body
        - author
      additionalProperties: false
      properties:
        name:
          type: string
          example: My first article
        headline:
          type: string
          description: Headline of the article.
          example: Traveling is great!
        article_body:
          type: string
          description: The actual body of the article.
          example: Traveling is great because...
        author:
          type: string
          description: The author of this content
          example: John Doe
        article_section:
          type: string
          example: discovery
          enum:
            - 'discovery'
            - 'travel'
            - 'update'
        tags:
          type: array
          items:
            type: string
            example: 'New York'

    Article:
      type: object
      properties:
        article:
          $ref: '#/components/schemas/ArticleBody'

    Collection:
      type: object
      properties:
        _links:
          type: object
        _embedded:
          type: object
          items:
            type: object

  requestBodies:
    ArticleBody:
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/ArticleBody'
      description: Article object.
      required: true

运行测试

$ phpdbg -qrr ./vendor/phpspec/phpspec/bin/phpspec run -f progress