php - 是否可以从不同的类或文件加载 Swagger 注释？

Question

我有以下简单的PHP方法，如下所示

/**
*
* (swagger annotation to be called from a different class)
*
*/
public function getApiCall()
{
  //Do something
}

而且我需要在方法上方的注释中包含长 Swagger 文档，那么
是否可以在不同的类中编写注释？并用类似的东西在这里调用它

/**
*
*call('App\Http\Controllers\testAnnotation');
*/

主要目的是拥有一个干净的类，其中没有太多的文档和注释行。

标签： phpannotationsswagger

Answer 1

加载“来自不同类的注释”并不是很有意义。在带注释的代码中读取注释，这就是它们的全部目的。

但是如果你想保持配置和代码分离，你不必使用Swagger -Php来生成你的 swagger 配置文件。

该包只是一种swagger.json从代码注释生成文件的便捷方式。

但是，如果您不想一开始就使用注释，并保持您的类免受无关配置的影响（我个人对此表示赞赏），那么...不要使用 Swagger-Php 并在您的类之外构建您自己的配置文件.

如果您觉得比手动编写 JSON 更舒服，您甚至可以用 YAML 编写它。例如：：

openapi: 3.0.0
info:
  title: 'Search API'
  version: 1.0.0
servers:
- url: 
  description: Current host server
- url: https:your-server.com
  description: Prod server
paths:
  /foo:
    post:
      summary: 'Creates a new foo'
      description: 'Builds a new Foo and makes it available to Bar'
      requestBody:
        description: 'Foo '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Foo'
      responses:
        '201':
          description: Foo created
        '202':
          description: Foo queued, it will be eventually created.
components:
  schemas:
    Foo:
      type: object
      required:
      - name
      - size
      properties:
        name:
          type: string
        size:
          type: integer

一旦转换为 JSON（有很多库可以做到这一点，或者您甚至可以使用像这样的免费服务），您可以直接将生成的 JSON 提供给 swagger。

例如，上面的 YAML 解析为这个 JSON 文件。您可以通过前往Swagger 演示实例并通过“探索”位置栏中的 JSON URL 轻松对其进行测试，您将得到如下内容：

最后，它并不比使用注解多多少工作（如果有更多工作的话），并且您可以保持实体类不受配置问题的影响。