README

该库受到nelmio/api-doc-bundle的启发；为PHP和Symfony工程师创建一种代码优先的体验。此软件使您能够通过PHP内置属性来记录事件和消息。

特性

• 代码优先的异步消息文档
• 内置由Async API React Component驱动的代码展示能力
• 由PHP反射驱动的自动化文档

安装

composer require ferror/asyncapi-doc-bundle

// config/bundles.php
return [
    Ferror\AsyncapiDocBundle\Symfony\Bundle::class => ['all' => true],
];

# config/packages/asyncapi_doc_bundle.yaml
ferror_asyncapi_doc_bundle:
  asyncapi_version: '2.6.0' # Async API specification version (default: 2.6.0)
  title: 'Service Example API'
  version: '1.2.3' # Your API version
  events: # The event class namespace
    - Ferror\AsyncapiDocBundle\Tests\Examples\UserSignedUp

# config/routes.yaml
ferror_asyncapi_doc_bundle_yaml:
    path: /asyncapi.yaml
    controller: ferror.asyncapi_doc_bundle.controller.yaml
    methods: GET

ferror_asyncapi_doc_bundle_json:
    path: /asyncapi.json
    controller: ferror.asyncapi_doc_bundle.controller.json
    methods: GET

ferror_asyncapi_doc_bundle_html:
    path: /asyncapi
    controller: ferror.asyncapi_doc_bundle.controller.ui
    methods: GET

最小使用方法

Async API Symfony Bundle将使用反射来确定属性的类型和名称。

如果您想手动定义它们，请查看其他示例。

use Ferror\AsyncapiDocBundle\Attribute\Message;
use Ferror\AsyncapiDocBundle\Attribute\Channel;

#[Message(name: 'ProductCreated')]
#[Channel(name: 'product.created')] // optional
final readonly class ProductCreated
{
    public function __construct(
        public int $id,
        public float $amount,
        public string $currency,
        public bool $isPaid,
        public DateTime $createdAt,
        public Week $week,
        public Payment $payment,
        public array $products,
        public array $tags,
    ) {
    }
}

使用方法

use Ferror\AsyncapiDocBundle\Attribute as AA;
use Ferror\AsyncapiDocBundle\Schema\Format;
use Ferror\AsyncapiDocBundle\Schema\PropertyType;

#[AA\Message(name: 'ProductCreated')]
#[AA\Channel(name: 'product.created')] // optional
final readonly class ProductCreated
{
    public function __construct(
        #[AA\Property(name: 'id', type: PropertyType::INTEGER)]
        public int $id,
        #[AA\Property(name: 'amount', type: PropertyType::FLOAT)]
        public float $amount,
        #[AA\Property(name: 'currency', type: PropertyType::STRING)]
        public string $currency,
        #[AA\Property(name: 'isPaid', type: PropertyType::BOOLEAN)]
        public bool $isPaid,
        #[AA\Property(name: 'createdAt', type: PropertyType::STRING, format: Format::DATETIME)]
        public DateTime $createdAt,
        #[AA\PropertyEnum(name: 'week', enum: Week::class)]
        public Week $week,
        #[AA\PropertyObject(name: 'payment', class: Payment::class)]
        public Payment $payment,
        #[AA\PropertyArrayObject(name: 'products', class: Product::class)]
        public array $products,
        #[AA\PropertyArray(name: 'tags', itemsType: 'string')]
        public array $tags,
    ) {
    }
}