Swagger-PHP，用于为Swagger-UI生成JSON文件

Question

我正在尝试使用Swagger-PHP来生成JSON文件，这样我就可以将它与Swagger-UI一起用于汽车文档。

我试过这个链接:- https://github.com/zircote/swagger-php

此外，我还尝试在http://zircote.com/swagger-php/installation.html上处理这些文档

但不幸的是，我无法实现它。

我能够正确地安装composer。此外，Swagger-PHP包也已正确安装。

但问题是我无法使用/理解他们提供的测试示例。

所以，如果有人解决了这个问题，请帮帮我！

提前感谢!！

Answer 1

你只需在你的代码中添加注释，模型示例：

/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
*  @SWG\Property(name="hostname", type="string"),
*  @SWG\Property(name="label", type="string"),
*  @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
    // ...
}

控制器示例：

/**
 * @SWG\Resource(
 *  basePath="http://skyapi.dev",
 *  resourcePath="/vps",
 *  @SWG\Api(
 *   path="/vps",
 *   @SWG\Operation(
 *    method="GET",
 *    type="array",
 *    summary="Fetch vps lists",
 *    nickname="vps/index",
 *    @SWG\Parameter(
 *     name="expand",
 *     description="Models to expand",
 *     paramType="query",
 *     type="string",
 *     defaultValue="vps,os_template"
 *    )
 *   )
 *  )
 * )
 */
 class VpsController extends Controller
 {
     // ...
 }

然后在控制台中：

php swagger.phar ./your-code-source/ -o ./directory-for-output-files

然后在Swagger UI中链接生成的文件。这是帮助吗？

顺便说一句，这个文档：http://zircote.com/swagger-php/annotations.html是不完整的。最好依靠解析器错误，例如：

php swagger.phar ./skynode-api/api/ -o ./foo
Swagger-PHP 0.9.0
-----------------
[INFO] Skipping unsupported property: "foo" for @Swagger\Annotations\Property, expecting "name", "description", "type", "format", "items", "uniqueItems", "required", "minimum", "maximum", "enum", "defaultValue", "_partialId", "_partials" in HostVps in /home/kane/some-dir/some-file.php on line 3

编辑：Swagger 2.0有非常好的规范on GitHub

顺便说一句，考虑使用Swagger Editor来创建在Swagger UI中使用的api规范文件(json/yaml)。因为php文件中的内联SWG文档太难看了，而且在IDE中也没有自动完成功能。

Answer 2

我最近一直在努力解决这个问题，看到了一些不同之处，并设法让它正常工作，并希望或许能为其他人提供捷径：

// In the controller

/**
 * (other swagger stuff like @SWG\Put, etc...)
 *   @SWG\Parameter(name="type",in="path",description="project|task",
 *                  required=true, type="array",             
 *                  @SWG\Items(type="string"), 
 *                  default="project",
 *                  enum={"project", "task"}),
 * (next @SWG\Parameter or closing paran, etc)
 */

我之前在模型中使用枚举和@SWG\Items引用获得了它，但没有保存该代码(我只是在胡闹)，而且我无法找回它。我甚至看到我之前提升了问题和接受的答案！但以上是我现在唯一能让它工作的方法，而且总比什么都没有好。