PHP Swagger и Yii

Я искал и обнаружил, что потерялся весь день, и я чувствую, что хожу по кругу.

Я написал (с помощью нескольких руководств) простой API для моего приложения на основе Yii.

Теперь я пришел, чтобы задокументировать этот API, чтобы другие могли его использовать. Я везде читал, что Swagger, кажется, подходит для реализации документации по API. Однако я могу понять, как использовать это приложение.

Я следовал инструкциям на Swagger PHP Теперь я потерялся, есть ли у кого-нибудь примеры того, что делать дальше.

Я попытался сделать некоторые аннотации моего ApiController.php, и это не работает. Я пытался использовать командную строку swagger.phar, но я все еще не понимаю, где. Я знаю, что вам понадобится гораздо больше информации, но я не знаю, какие части информации вам нужны, поэтому вместо того, чтобы вставлять много бесполезной информации, пожалуйста, спросите, и я пришлю все, что вам нужно.

Честно говоря, все, что я хотел бы, это простая документация по API, но это кажется невозможным.

Ваше здоровье


php api swagger yii swagger-php
person Liam    schedule 02.07.2014    source источник
comment
Вопрос: Почему бы вам не начать с документации, как это делается в APIARY.IO, а не начать с реализации на PHP? Звучит как правильный путь для меня.   -  person lin    schedule 02.07.2014
comment
Проверяю это сейчас, это кажется немного проще, спасибо, Лиам.   -  person Liam    schedule 02.07.2014
comment
Проверьте прокси-инструмент, который позволяет вам туннелировать ваш проект APIARY.IO в ваши тестовые/разработочные/сценические/живые системы. Ваше здоровье.   -  person lin    schedule 02.07.2014

Ответы (1)


arrow_upward
2
arrow_downward

Я реализовал swagger-php в своем проекте. Пожалуйста, следуйте приведенным ниже инструкциям:

1) Загрузите swagger-php (github.com/zircote/swagger-php) и swagger-ui (github.com/wordnik/swagger-ui). Извлеките их в свое рабочее пространство.

2) Создайте папку с именем swagger-api и пустой файл php с именем index.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) Откройте index.html в swagger-ui/dist/

8) Заменить -: url: "http://petstore.swagger.wordnik.com/api/api-docs" на URL: "http:localhost/swagger-docs"

9) Запустите localhost/swagger-ui/dist в своем браузере.

person triju    schedule 29.09.2014
comment
не могли бы вы объяснить больше, потому что я не понимаю точного представления - person Yagnesh Panchal; 14.03.2018