3

我搜索了一下，发现我已经迷路了一整天，我觉得我在兜圈子。

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

我现在来记录这个 API 以供其他人使用。我到处读到 Swagger 似乎是实现 API 文档的方法。但是，我似乎可以在任何地方了解如何使用此应用程序

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

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

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

干杯

4

1 回答 1

2

我已经在我的项目中实现了 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 docs 文件夹中创建的一些文件。

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。

于 2014-09-29T13:46:32.340 回答