使用 SLIM 和 SWAGGER 的 RESTful API 文档？

Posted 2023-03-04

【中文标题】使用 SLIM 和 SWAGGER 的 RESTful API 文档？

【英文标题】：RESTful API Doc using SLIM and SWAGGER?

【发布时间】：2014-06-17 06:33:58

【问题描述】：

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

干杯并感谢您的耐心:)

【问题讨论】：

我听说了 Swagger 的好消息 - 相关网站上是否有任何文档？然而，我的猜测是这个话题在这里太宽泛了——请记住，Stack Overflow 是针对涉及代码的编程问题。如果你可以试一试并编辑这个关于what的问题，那就太好了。

我不知道如何在我的 php 项目中集成 swagger。他们在 Github 上提供了一个 php 客户端和一个用于 Java 的服务器集成教程，但这并没有让我走得更远。目前我不知道我必须采取哪些步骤。我不想将 cmets 放在我的源代码中，然后运行一个创建文档的工具。

【参考方案1】：

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');
);

【参考方案2】：

我想你正在寻找这个项目：zircote/swagger-php

Here 您将了解如何根据用户对 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 文档。

【讨论】：

谢谢！但是我如何将 swagger-UI 与之集成呢？

启动并运行 :)

@user2942586 您能解释一下您是如何启动和运行它的吗？

@LeonardChallis 你需要安装 swagger-ui:github.com/swagger-api/swagger-ui 并使其指向 swagger 路由。

谢谢@adosaiguas