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

问题描述

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

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

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

我还尝试使用 http://zircote.com/swagger-php/installation.html

但我运气不好，我无法实现它.

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

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

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 !!

提前致谢！！

推荐答案

你只需在你的代码中添加注释，也就是注解，模型示例:

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

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

控制器示例:

/**
 * @SWGResource(
 *  basePath="http://skyapi.dev",
 *  resourcePath="/vps",
 *  @SWGApi(
 *   path="/vps",
 *   @SWGOperation(
 *    method="GET",
 *    type="array",
 *    summary="Fetch vps lists",
 *    nickname="vps/index",
 *    @SWGParameter(
 *     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 中链接生成的文件.这有帮助吗?

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

顺便说一句，此文档:http://zircote.com/swagger-php/annotations.html 不完整.最好依赖解析器错误，例如:

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 @SwaggerAnnotationsProperty, 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 有很好的规范 在 GitHub 上

EDIT: Swagger 2.0 has pretty good specification on GitHub

顺便说一句，考虑使用 Swagger Editor 创建 api 规范文件 (json/yaml) 以在 Swagger 中使用用户界面.因为 php 文件中的内联 SWG 文档很难看，而且您在 IDE 中没有自动完成支持.

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屋！