symfony7之NelmioApiDocBundle的使用

• 链接:https://github.com/nelmio/NelmioApiDocBundle

• 主要使用如下composer包:

  nelmio/api-doc-bundle
  

• 这个包会依赖:

  zircote/swagger-php
  
  在nelmio/api-doc-bundle的composer.json下有定义
  

项目中使用:

1.定义配置文件(nelmio_api_doc.yaml)

nelmio_api_doc:
documentation:
info:
title: Qinhong
description: Event platform provided by QH AG
version: 1.0.0
components:
securitySchemes:
qinHongHeaderApiKey:
type: apiKey
in: header
name: X-QINHONG-API-TOKEN
Bearer:
type: http
scheme: bearer
in: header
bearerFormat: JWT
security:
- Bearer: []
areas:
path_patterns: # an array of regexps (document only routes under /api, except /api/doc)
- ^/api(?!/doc$)
documentation:
security:
- qinHongHeaderApiKey: [ ]
- Bearer: [ ]

其中:

info 定义了基本的信息
securitySchemes 定义了几种接口认证方式
security 定义了默认全局的认证方式
areas 定义了接口作用域
areas.path_patterns 定义了哪些路由将会生成接口
areas.documentation.security 定义了当前area下要使用的认证方式

2.控制器下使用

use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Attributes as OA; //定义在zircote/swagger-php


#[Route('/country-distribution-count', name: 'country_distribution_count', methods: ['GET'])]
#[OA\Response(
response: 200,
description: 'Return all country distribution count',
content: new Model(type: Dto\Query\Statistic\DistributionCountDto::class)
)]
public function test(
Service\\RegistrationService $statisticsService,
): JsonResponse {
return $this->apiResponse->response($statisticsService->test());
}

当然还有其它的注释类可以使用，这里使用的是 OA\Response