I'm using zircote/swagger-php to generated API documentation based on OpenApi annotations that I have added to existing code.
For the most part it's working fine, but I've noticed one strange bit. I have a method, indexAction(), that is supposed to return a list of items:
/**
* @OA\Get(
* path="\location",
* description="Retrieves a list of locations for the current organisation",
* method="indexAction",
* @OA\Response(
* response="200",
* description="List of locations",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Location")
* ),
* @OA\XmlContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Location")
* )
* )
* )
*/
public function indexAction()
{
After compiling the documentation json file, I open it and this action is listed as follows:
"paths": {
"\\location": {
"get": {
"summary": "The index action handles index/list requests; it should respond with a\nlist of the requested resources.",
"description": "Retrieves a list of locations for the current organisation",
"operationId": "2b36ea7d6a6e350fd6c7564bc908a25b",
"responses": {
"200": {
"description": "List of locations",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Location"
}
}
},
"application/xml": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Location"
}
}
}
}
}
}
}
},
For some reason the "path" is listed as \\location instead of, as I expect, \location - does anyone know why this is happening? I hope this is enough, if more code is required I can supply it.
\\ is just an escaped version of the \ character in JSON strings. That is, the actual value of the "\\location" string is \location.
However, URL paths use / forward slashes, and OpenAPI also requires that paths start with /. So you need to replace
path="\location",
with
path="/location",