Swagger-PHP，用于为Swagger-UI生成JSON文件 [英] Swagger-PHP for generating JSON file for Swagger-UI

问题描述

我正在尝试使用Swagger-PHP生成JSON文件，以便可以将其与Swagger-UI一起用于自动文档编制。

我尝试了以下链接： - https://github.com/zircote/swagger-php

我也尝试使用 http：// zircote上的文档.com / swagger-php / installation.html

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

我能够正确安装作曲家。
Swagger-PHP捆绑包也已正确安装。

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

因此，如果有人解决了这个问题，请帮助!!

提前感谢！

解决方案

您只需在代码中添加注释，也就是注释，例如：

  / ** 
 * @ 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']）
 *）
 * / 
类HostVps扩展宿主实现ResourceInterface 
 {
 // ... 
} 
  

控制器示例：

  / ** 
 * @ SWG\Resource（
 * basePath = http：// s kyapi.dev，
 * resourcePath = / vps，
 * @ SWG\Api（
 * path = / vps，
 * @ SWG\Operation （
 * method = GET，
 * type = array，
 * summary =获取vps列表，
 *昵称= vps / index，
 * @ SWG\Parameter（
 * name = expand，
 * description =扩展模型，
 * paramType = query，
 * type = string，
 * defaultValue = vps，os_template 
 *）
 *）
 *）
 *）
 * / 
类VpsController扩展了控制器
 {
 // ... 
} 
  

然后在控制台中

  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]跳过不受支持的属性：@ Swagger＼的 foo ＼注释\属性，期望名称，描述，类型，格式，项目， uniqueItems，必需，最小，最大，枚举， defaultValue /home/kane/some-dir/some-file.php中第3行的HostVps中的，_partialId， _ partials 
  

编辑：Swagger 2.0具有很好的规范在GitHub

BTW，请考虑使用 Swagger编辑器来创建要在Swagger UI中使用的api规范文件（json / yaml）。因为php文件中的内联SWG文档太丑陋，并且您在IDE中没有自动完成支持。

I am trying to use Swagger-PHP for generating JSON files , so that I can use it with Swagger-UI for auto documentation.

I tried the link :- https://github.com/zircote/swagger-php

Also I tried to work around with there documentation at http://zircote.com/swagger-php/installation.html

But my hard luck , I am unable to implement it.

I am able to install composer correctly. Also the bundle of Swagger-PHP is installed correctly.

But the problem is that I am unable to use/understand the test examples provided by them.

So if anyone has worked it around please help !!

Thanks in advance !!

解决方案

You just put comments aka annotations in your code, model example:

/**
* @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
{
    // ...
}

Controller example:

/**
 * @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
 {
     // ...
 }

Then in console:

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

Then link generated files in Swagger UI. Is this help?

BTW, this documentation: http://zircote.com/swagger-php/annotations.html is incomplete. It's better to rely on parser errors, example:

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

EDIT: Swagger 2.0 has pretty good specification on GitHub

BTW, consider to use Swagger Editor to create api specification file (json/yaml) to use in Swagger UI. Cause inline SWG documentation in php files is just ugly and you don't have autocomplete support in IDE.

这篇关于Swagger-PHP，用于为Swagger-UI生成JSON文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！