PHP Swagger 和 Yii

Question

找了一整天，发现自己迷路了，感觉在原地打转。

我已经为基于 Yii 的应用程序编写了一个简单的 API(在一些指南的帮助下)。

我现在已经开始记录这个 API 以供其他人使用。我到处都读到 Swagger 似乎是实现 API 文档的方式。但是我似乎可以了解如何使用此应用程序

我已按照 Swagger PHP 上的说明进行操作现在我迷路了，有没有人有任何下一步该做什么的例子。

我已经尝试对我的 ApiController.php 进行一些 self 注释，但这不起作用。我一直在尝试使用 swagger.phar 命令行，但我仍然不知道在哪里。我知道您需要更多信息，但我不知道您需要哪些信息，所以与其粘贴大量无用信息，请询问，我会发送您需要的任何信息。

老实说，我只想要一些简单的 API 文档，但这似乎是不可能的。

干杯

Answer 1

我在我的项目中实现了 swagger-php。请按照以下建议的说明进行操作:

1) 下载swagger-php(github.com/zircote/swagger-php)和swagger-ui(github.com/wordnik/swagger-ui)。将它们提取到您的工作区。

2) 在您的工作区中创建一个名为 swagger-api 的文件夹和一个名为 index.php 的空白 php 文件，然后粘贴以下代码。

<?php
  use Swagger\Annotations as SWG;


/**
 * @SWG\Resource(
 *     apiVersion="0.2",
 *     swaggerVersion="1.2",
 *     resourcePath="/api.php",
 *     basePath="http://localhost/swagger-api/"
 * )
 */


// Run this in url

// localhost/index.php?action=get_app_list


// This is the API,show the list in array


/**
     *
     * @SWG\Api(
     *   path="/api.php?action=get_app_list",
     *   description="Operations about get app list",
     *   produces="['application/json']",
     *   @SWG\Operations(
     *     @SWG\Operation(
     *       method="GET",
     *       summary="Find facet by ID",
     *       notes="Returns a facet based on ID",
     *       type="ListResult",
     *       nickname="getAllResults", 
     *       @SWG\ResponseMessages(
     *          @SWG\ResponseMessage(
     *            code=400,
     *            message="Invalid ID supplied"
     *          ),
     *          @SWG\ResponseMessage(
     *            code=404,
     *            message="facet not found"
     *          )
     *       )
     *     )
     *   )
     * )
     */

    function get_app_list()
    {
      //normally this info would be pulled from a database.
      //build JSON array
      $app_list = array(array("id" => 1, "name" => "Web Demo"), 
    array("id" => 2, "name" => "Audio Countdown"), 
    array("id" => 3, "name" => "The Tab Key"), array("id" => 4,
    "name" => "Music Sleep Timer")); 
      return $app_list;
    }



    $possible_url = array("get_app_list");

    $value = "An error has occurred";

    if (isset($_GET["action"]) && in_array($_GET["action"], $possible_url))
    {
      switch ($_GET["action"])
        {
          case "get_app_list":
        $value = get_app_list();
        break;     
          $value = "Missing argument";
        break;
        }
    }

    //return JSON array
    echo(json_encode($value));
    ?>

3) 在工作空间中创建名为 swagger-docs 的文件夹。

4) 打开您的终端并转到您工作区中 swagger-php 的位置(即 cd workpace/swagger-php)。

5) 在您的终端中执行以下命令 php swagger.phar/workspace/swagger-api -o/workspace/swagger-docs(这可以在我们包含 swagger.phar 文件的地方执行)。

6) 您将看到在您的 swagger 文档文件夹中创建了一些文件。

7)在swagger-ui/dist/中打开index.html

8) 将 -: url: "http://petstore.swagger.wordnik.com/api/api-docs "替换为 url: "http:localhost/swagger-docs"

9) 在浏览器中运行 localhost/swagger-ui/dist。