使用 SLIM 和 SWAGGER 的 RESTful API 文档？

Question

我对这个东西很陌生，但我喜欢它。我使用 Slim Framework 制作了一些 REST Api。现在我想要一份关于它的持续文档。我认为 swagger 是正确的选择，但我还没有找到如何集成它？

干杯并感谢您的耐心:)

Answer 1

我认为您正在寻找这个项目：zircote/swagger-php

在这里您将了解如何根据用户对 URL 的请求生成文档。

基本上，您必须使用 Swagger Annotations 来注释您的代码，然后使用与此类似的代码在 Slim 中创建另一个路由：

<?php
use Swagger\Swagger;
$swagger = new Swagger('/project/root/top_level');
header("Content-Type: application/json")
echo $swagger->getResource('/pet', array('output' => 'json'));

它将为您即时生成 Swagger API 文档。

Answer 2

对 adosaiguas 的答案进行简短更新：

使用Slim Framework 4.0和zircote/swagger-php时 可以使用以下代码提供 swagger / OpenAPI 3.0 json 描述的 api 端点：

use function OpenApi\scan;

 /**
 * @OA\Get(
 *     path="/openapi",
 *     tags={"documentation"},
 *     summary="OpenAPI JSON File that describes the API",
 *     @OA\Response(response="200", description="OpenAPI Description File"),
 * )
 */
$app->get('/openapi', function ($request, $response, $args) {
    $swagger = scan('--PATH TO PROJECT ROOT--');
    $response->getBody()->write(json_encode($swagger));
    return $response->withHeader('Content-Type', 'application/json');
});

Answer 3

当您正在寻找完全从 PHP 代码自动派生的 Swagger 集成时，您可以查看我的最新项目：https://github.com/lnaegele/PSwag

该项目基于 Slim 并提供 OpenAPI 3.0 规范和“动态”的 swagger 页面 - 无需您进行任何手动生成步骤。您只需为 API 方法的参数和返回指定数据类型。

示例：在PetApplicationService.class中创建端点函数：

/**
 * Find pet by ID
 * @param int $petId ID of pet to return
 * @return Pet Returns a single pet
 */
public function getPetById(int $petId): Pet {
    return new Pet(...);
}

在您的 index.php 中，您在 PSwagApp 中注册端点，它是 SlimApp 的包装器：

// create SlimApp and wrapper PSwagApp
$slimApp = AppFactory::create();    
$app = new PSwagApp($slimApp);

...

// add swagger middleware
$app->addSwaggerUiMiddleware('/swagger', 'PSwag example', '1.0.0', 'vendor/swagger-api/swagger-ui/dist/');

// register endpoints by specifying class and method name
$app->get('/pet/{petId}', [PetApplicationService::class, 'getPetById']);

结果将如下所示：