README

Laravel 包，能够通过测试自动生成 API 文档，无需在代码库中添加垃圾注释。

文档支持

1. OpenAPI 3.0.0

工作原理

如果你的项目有优秀的功能测试覆盖率，这意味着你已经为该项目创建了文档。你已经描述了可用的路径、请求体、参数、内容类型、响应负载和 HTTP 状态码。你不应该再用自己的方式重新描述，只是格式为使用的 API 文档格式。该包的原则非常简单：当你运行测试时，包中间件会抓取测试用例的响应和请求，并将其保存为 API 文档配置文件，你可以使用它来渲染。

安装

1. 使用 composer require --dev futurfuturfuturfutur/duckduckduck 安装包
2. 发布和设置包，使用 php artisan duckduckduck:init。此命令将在 Laravel 的 config 文件夹中发布 duckduckduck.php 配置文件，包含你的 API 文档的基本配置，并在应用的根目录中创建 /duckduckduck 包目录，用于存储由包生成的所有项目文档配置。
3. 在 PHPUnit TestCase 中添加 TestCase 特性

   <?php
   
   namespace Tests;
   
   use Futurfuturfuturfutur\Duckduckduck\Traits\DuckduckduckTestCase;
   use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
   
   abstract class TestCase extends BaseTestCase
   {
       use CreatesApplication;
       use DuckduckduckTestCase;
       ...
   }

用法

设置

该包将处理大多数事情，但其中一些你需要自己定义

1. 在 config/duckduckduck.php 中定义 API 文档的基本信息（名称、描述、文档类型、版本）
2. 在测试类的 PHPDoc 注释中定义路由描述和分组（所有这些都是可选的）

   /**
    * @DuckDuckDuckRouteGroup Group name
    * @DuckDuckDuckRouteDescription Description
    */
   class IndexTest extends TestCase
   {

3. 在案例方法的 PHPDoc 注释中定义测试案例描述

   /**
    * @DuckDuckDuckRouteDescription Description of the case
    */
   public function testShow()
   {

运行构建

使用 php artisan duckduckduck:generate 运行 API 文档生成模式的测试。该包将运行你的应用的特性测试并生成位于应用根目录下包 /duckduckduck 目录中的文档文件。

使用 Docker 运行文档渲染

运行文档渲染服务器的最简单和最优雅的方式是启动包含 /duckduckduck 包目录的 docker 容器。

Swagger

docker run -p 9999:8080 -e SWAGGER_JSON=/duckduckduck/swagger.json -v /duckduckduck:/duckduckduck swaggerapi/swagger-ui

请记住，挂载 duckduckduck 文件夹时应定义绝对路径

API 文档

• 文档的基本信息
• 分组路径及其描述和方法
• 请求中的路径、查询和体参数
• 具有负载和代码的路由响应
• 运行 API 的服务器的信息
• 表单请求的参数验证规则

贡献

请参阅贡献指南以获取详细信息。

许可证

MIT 许可证 (MIT)。请参阅许可证文件以获取更多信息。