0

在我使用 swagger-php 的项目中，在生产服务器上我收到验证错误“对象缺少必需的属性 ([\"paths\"])”。尽管这个错误招摇 UI 工作正常。

我的 php 文件中的注释：

/**<br />
 * @SWG\Swagger(<br />
 *  @SWG\Info(<br />
 *      title="Заголовок",<br />
 *      description="Описпание",<br />
 *      contact={<br />
 *          "name": "Дмитрий Сабиров",<br />
 *          "email": "test@yandex.ru"<br />
 *      },<br />
 *      license={<br />
 *          "name": "MIT",<br />
 *          "url": "https://opensource.org/licenses/MIT"<br />
 *      },<br />
 *      version="1.0.0"<br />
 *  ),<br />
 *  schemes={"http"},<br />
 *  host=API_HOST,<br />
 *  basePath="/api"<br />
 * )<br />
 */<br />

和

/**<br />
 * @SWG\Get(<br />
 *  description="Проверка существования пользователя с данным емайлом.",<br />
 *  path="/users/check-email",<br />
 *  produces={"application/json"},<br />
 *  @SWG\Parameter(<br />
 *          name="email",<br />
 *          in="query",<br />
 *          description="проверяемый емайл",<br />
 *          required=true,<br />
 *          type="string"<br />
 *  ),<br />
 *  @SWG\Response(<br />
 *    response=200,<br />
 *    description="Если пользователь не существует - создаётся и ысылается письмо.",<br />
 *    @SWG\Schema(<br />
 *          type="object",<br />
 *          @SWG\Items(<br />
 *              @SWG\Property(<br />
 *                  property="emailExist",<br />
 *                  type="boolean"<br />
 *              ),<br />
 *              @SWG\Property(<br />
 *                  property="userCreated",<br />
 *                  type="boolean"<br />
 *              ),<br />
 *              @SWG\Property(<br />
 *                  property="sentActivationEmail",<br />
 *                  type="boolean"<br />
 *              )<br />
 *          ),<br />
 *          example={<br />
 *              "application/json": {<br />
 *                  "emailExist": true,<br />
 *                  "userCreated": false,<br />
 *                  "sentActivationEmail": false<br />
 *              }<br />
 *          }<br />
 *    )<br />
 *  ),<br />
 *  @SWG\Response(<br />
 *     response=500,<br />
 *     description="внутренняя ошибка сервера",<br />
 *  )<br />
 * )<br />
 */<br />

招摇 api 响应是：

{
  "swagger": "2.0",
  "info": {
    "title": "Заголовок",
    "description": "Описпание",
    "contact": {
      "name": "Дмитрий Сабиров",
      "email": "test@yandex.ru"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0.0"
  },
  "host": "46.36.218.161",
  "basePath": "/api",
  "schemes": ["http"],
  "paths": {
    "/users/check-email": {
      "get": {
        "description": "Проверка существования пользователя с данным емайлом.",
        "produces": ["application/json"],
        "parameters": [{
          "name": "email",
          "in": "query",
          "description": "проверяемый емайл",
          "required": true,
          "type": "string"
        }],
        "responses": {
          "200": {
            "description": "Если пользователь не существует - создаётся и высылается письмо.",
            "schema": {
              "type": "object",
              "items": {
                "properties": {
                  "emailExist": {
                    "type": "boolean"
                  },
                  "userCreated": {
                    "type": "boolean"
                  },
                  "sentActivationEmail": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "application/json": {
                  "emailExist": true,
                  "userCreated": false,
                  "sentActivationEmail": false
                }
              }
            }
          },
          "500": {
            "description": "внутренняя ошибка сервера"
          }
        }
      }
    }
  },
  "definitions": {}
}

但大摇大摆的 UI doc 返回错误：

{
  "messages": ["attribute paths is missing"],
  "schemaValidationMessages": [{
    "level": "error",
    "domain": "validation",
    "keyword": "required",
    "message": "object has missing required properties ([\"paths\"])",
    "schema": {
      "loadingURI": "#",
      "pointer": ""
    },
    "instance": {
      "pointer": ""
    }
  }]
}

如何修复此错误？

4

1 回答 1

1

验证器徽章使用 swagger.io 上的在线 Swagger 验证器来验证您的规范。验证器请求：

http://online.swagger.io/validator?url=http://46.36.218.161/site/api

online.swagger.io 上的验证服务器直接从 URL 加载您的规范，并且不使用任何授权（无 API 密钥、基本身份验证等）。如果没有授权，您的规范 URL ( /site/api) 将返回以下内容：

{
  "securityDefinitions": {
    "api_key": {
      "in": "header",
      "type": "apiKey",
      "name": "api_key"
    }
  },
  "swagger": "2.0",
  "schemes": [
    "http"
  ],
  "info": {
    "title": "Please take authentication firstly."
  }
}

这不是有效的 OpenAPI/Swagger 规范，因为它不包含paths密钥。这就是验证器返回错误的原因。


为避免该错误，您可以执行以下操作之一。

1) 修改您的规范生成器，使初始（未经身份验证的）规范包括"paths": {}：

{
  "swagger": "2.0",
  ...
  "paths": {}
}

这将使规范有效。

2) 隐藏验证者徽章。为此，请添加validatorUrl: nullSwagger UI 页面的 HTML 代码：

window.swaggerUi = new SwaggerUi({
  url: url,
  ...
  validatorUrl: null
});
于 2018-01-16T18:21:56.983 回答