标签: swagger-php

对于用PHP编写一些REST API的,我被要求创建扬鞭的文件,因为我不知道的添加注解这些现有的API和创建这样的文件没有简单的方法,我用这个编辑器生成一些现在.

我保存了使用该编辑器创建的JSON和YAML文件,现在我需要创建最终的交互式Swagger文档(这个声明可能听起来很幼稚和模糊).

有人可以告诉我如何将Swagger JSON规范文件转换为实际的Swagger文档吗？

我在Windows平台上,对Ant/Maven一无所知.

我是新手,但我喜欢它.我使用Slim Framework做了一点REST Api.现在我想有一个关于它的持续文档.我认为招摇是正确的选择,但我还没有找到如何整合它？

干杯谢谢你的耐心:)

我有一个使用Codeigniter的REST Web服务并使用这个库:https://github.com/chriskacerguis/codeigniter-restserver

我想为这个Web服务生成文档.我希望使用Swagger UI来生成此文档.但是,我没有找到任何文档如何使用Swagger与Codeigniter.

使用这两种技术的唯一项目是这一项,但没有一份好的文档:https://github.com/panxp/codeigniter-swagger

有人可以使用这两种技术粘贴一个例子,或者给我一个良好文档的链接？当然,如果有另一个好的lib来生成文档,如果它可以与Codeigniter一起使用,我会接受它.

我正在处理大量带有带有 Swagger PHP 注释的 PHP 块文档的文件，但是它们没有缩进。反正有没有用空格自动格式化它们？

车削

/**
 * @SWG\Api(
 * path="/building/{buildingId}",
 * @SWG\Operation(
 * method="GET",
 * type="Building",
 * summary="Returns a Building object by ID",
 * nickname="building/getBuilding",
 * @SWG\Parameter(
 * name="buildingId",
 * description="ID of the building that needs to be fetched",
 * paramType="path",
 * required=false,
 * type="string",
 * defaultValue="1"
 * )
 * )
 * )
 */

进入

/**
 * @SWG\Api(
 *   path="/building/{buildingId}",
 *   @SWG\Operation(
 *     method="GET",
 *     type="Building",
 *     summary="Returns a Building object by ID",
 *     nickname="building/getBuilding",
 *     @SWG\Parameter(
 * …

我正在使用Swagger PHP,并且大多数定义很容易定义,但我遇到的问题是某个特定的数据不属于单独的类,而是一个关联数组.

我希望展示的json响应(针对此问题进行了简化):

{
"id": 1,
"status": "published",
"gps": {
    "lat": "0.00000000",
    "lng": "0.00000000"
}

的id和status足够易于限定,然而,gps是一个问题,因为没有单独的类中定义它,它是模型内的阵列.是否可以定义此数组而无需创建虚拟类？

目前模型文件中的注释:

/**
 * @SWG\Definition(@SWG\Xml(name="Event"))
 */
 class Event extends BaseModel {
     /**
     * @SWG\Property(
     *      property="id",
     *      type="integer",
     *      example="103"
     * )
     * @SWG\Property(
     *      property="status",
     *      type="string",
     *      enum={"published", "draft", "suspended"}
     *      example="published"
     * )
     */

 }

我使用这些包（通过作曲家安装）

"swagger-api/swagger-ui": "^3.0",
"zircote/swagger-php": "~2.0|3.*"

在我的 def 控制器中，我有这些注释

/**
 * @OA\Info(title="My API", version="0.1")
 * @OA\Schemes(format="http")
 * @OA\SecurityScheme(
 *      securityScheme="bearerAuth",
 *      in="header",
 *      name="Authorization",
 *      type="http",
 *      scheme="Bearer",
 *      bearerFormat="JWT",
 * ),
 * @OA\Tag(
 *     name="Auth",
 *     description="Auth endpoints",
 * )
 * @OA\Tag(
 *     name="Users",
 *     description="Users endpoints",
 * )
 */
class Controller extends BaseController

然后我有方法

/**
 * 
 * @OA\Get(
 *      path="/users",
 *      operationId="getListOfUsers",
 *      tags={"Users"},
 *      description="Get list of users",
 *      security={{"bearerAuth":{}}}, 
 *      @OA\Parameter(
 *         name="Authorization",
 *         in="header",
 *         required=true, …

我正在使用 swagger-php 注释来生成我的 REST API 的文档，并且我想使用预定义的示例来描述响应。

下面的 YAML 代码有效：

components:
  examples:
    exampleUser:
      value:
        id: 1
        name:   "Alan Cool"
        email:  "joe@cool.com.br"
        password:   "string"
        status: "string"
        ultimo_acesso:  155850122
        cpf:    "string"
        rg: "string"
        cargo:  "string"
        grupo_id:   7
        empresa_id: 88
        thumbnail_id:   99
        loja_id:    1299

但是，当尝试通过注释生成上面的代码时，我无法让它工作。我正在尝试：

/**
 * @OA\Examples(
 *    summary = "exampleUser",
 *    description = "exampleUser",
 *    value = "exampleUser"
 * )
 */

到目前为止，似乎没有关于 PHP 注释的说明。有什么建议？

我使用L5-Swagger 5.7。*软件包（Swagger-php的包装器），并尝试描述Laravel REST API。所以，我的代码是这样的：

/**
 * @OA\Post(path="/subscribers",
 *     @OA\RequestBody(
 *         @OA\MediaType(
 *            mediaType="application/json",
 *            @OA\Schema(
 *               type="object",
 *               @OA\Property(property="email", type="string")
 *            )
 *        )
 *    ),
 *   @OA\Response(response=201,description="Successful created"),
 *   @OA\Response(response=422, description="Error: Unprocessable Entity")
 * )
 */
public function publicStore(SaveSubscriber $request)
{
    $subscriber = Subscriber::create($request->all());
    return new SubscriberResource($subscriber);
}

但是当我尝试通过swagger面板发送请求时，我得到了代码：

curl -X POST "https://examile.com/api/subscribers" -H "accept: */*" -H "Content-Type: application/json" -H "X-CSRF-TOKEN: " -d "{\"email\":\"bademail\"}"

如您所见，accept不是application / json，并且Laravel不会将其识别为AJAX请求。因此，当我发送错误的数据并期望实际获得422错误时，我在“会话”中获得200错误代码。通过招摇面板的请求（XHR）也会被错误地处理，CURL代码只是为了清楚起见。

另外，我发现在以前的版本中使用了类似以下内容：

* @SWG\Post(
*     ...
*     consumes={"multipart/form-data"},
*     produces={"text/plain, …

我担心使用Swagger为我的GET请求生成Model/Example值部分. 官方示例的链接显示该部分完美.

在官方文档中,它是使用现有模型生成的:

     *     @SWG\Schema(ref="#/definitions/User")

我没有这样的选项,因为我的属性是由REST生成的.

我尝试过以下方式:

/**
 * @SWG\Get(
...
 *     @SWG\Response(
 *         response="200",
 *         description="Ok",
 *         @SWG\Schema(
 *             type="array",
 *             @SWG\Property(property="firstname", type="string", example="Steven")
 *         ),
 *     ),
 * )
 */

它没有工作和答案:

fetching resource list: http://localhost/dist/swagger.json; Please wait.

任何帮助都非常感谢.提前致谢.

我用Swagger-php.当我定义查询字符串上的参数时,它可以是一个数组.但从我所看到的,它不支持这种查询字符串:

https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12

我相信如果可能的话,这将在collectionFormat现场设置.目前我一直在使用pipes,但我想使用上述格式,并且Swagger-UI也反映了这一点.但是,我读到了这个github问题,这让我想知道这是否真的可行而且我错过了它？

我的Swagger-PHP定义的一个例子:

/**
*     @SWG\Parameter(
*         name="ids",
*         in="query",
*         description="A list of IDs (separated by pipes) to filter the Returns",
*         required=false,
*         type="array",
*         @SWG\Items(
*             type="integer",
*             format="int32"
*         ),
*         collectionFormat="pipes"
*     )
*/

这导致以下JSON:

"parameters": {
    "ids": {
        "name": "ids",
        "in": "query",
        "description": "A list of IDs (separated by pipes) to filter the Returns",
        "required": false,
        "type": "array",
        "items": {
            "type": "integer",
            "format": "int32"
        }, …