使用SLIM和SWAGGER编写RESTful API文档？

Question

我是一个新手，但我喜欢它。我用Slim框架创建了一个小型的REST API。现在我想要一份持续的关于它的文档。我认为Swagger是正确的选择，但我还没有弄清楚如何集成它？

祝好 & 感谢您的耐心 :)

- user2942586

---

我听说Swagger很不错 - 相关网站上有文档吗？然而，我猜这个话题在这里太广泛了 - 请记住，Stack Overflow是用于涉及代码的编程问题。如果你能尝试并编辑这个问题关于你卡在哪里，那就太好了。 - halfer

我不知道如何在我的PHP项目中集成Swagger。他们在Github上提供了一个PHP客户端和一个用于Java的服务器集成教程，但这并没有让我进一步。目前我不知道应该采取哪些步骤。我不想在我的源代码中加注释，然后运行一个工具来创建文档。 - user2942586

Answer 1

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

在这里您将找到如何根据用户请求生成文档的方法。

基本上，您需要使用Swagger注释对代码进行注释，然后在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文档。

- adosaiguas

---

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

搞定并运行中 :) - user2942586

@user2942586，您能否请详细解释一下您是如何使其运行起来的呢？ - LeonardChallis

您需要安装Swagger-UI：https://github.com/swagger-api/swagger-ui，并将其指向Swagger路由。 - adosaiguas

感谢 @adosaiguas - LeonardChallis

Answer 2

关于adosaiguas回答的最新更新：

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

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

- fox918