Swagger-PHP attribute paths is missing

Question

In the project I use swagger-php and on production server I get the validation error "object has missing required properties ([\"paths\"])". Despite this error swagger UI working fine.

Annotations in my php files:

/**<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 />

and

/**<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 />

swagger api response is :

{
  "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": {}
}

but swagger UI doc return error :

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

how fix this error ?

Answer 1

The validator badge uses the online Swagger Validator at swagger.io to verify your spec. The validator makes the request to:

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

The validation server at online.swagger.io loads your spec directly from URL and does not use any authorizations (no API keys, Basic auth, etc.) Without authorization, your spec URL (/site/api) returns the following:

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

This is not a valid OpenAPI/Swagger spec, because it does not include the paths key. That's why the validator returns the error.

To avoid the error, you can do one of the following.

1) Modify your spec generator so that the initial (unauthenticated) spec includes "paths": {}:

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

This will make the spec valid.

2) Hide the validator badge. To do this, add validatorUrl: null in the HTML code of your Swagger UI page:

window.swaggerUi = new SwaggerUi({
  url: url,
  ...
  validatorUrl: null
});