是否可以从其他类或文件加载Swagger注释？

Question

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

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

并且我需要在该方法上方的注释中包含较长的Swagger文档，所以
是否可以在其他类中编写注释？并在此处使用类似的名称

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

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

Answer 1

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

但是，如果要将配置和代码分开，则不必不必使用Swagger-Php来生成庞大的配置文件。

该软件包只是从代码注释生成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（有许多库可以执行此操作，或者甚至可以使用免费服务like this one），就可以将生成的JSON直接输入。

例如上方的YAML解析为this JSON file。您可以通过转到Swagger demo instance并在“ explore”位置栏中经过JSON URL轻松地对其进行测试，您将获得类似以下内容的信息：

最后，与使用批注相比，它的工作量不多（如果还有更多工作的话），并且您可以使实体类免受配置方面的困扰。