Definition paths not supported?

[SAThomsen]

Hey guys, I have a quite large project and so I decided to bundle my definitions into subfolders. I have some models that I ideally would name the same and so I've done something like the following:

{
    "swagger": "2.0",
    "info": {
        "title": "Test API",
        "description": "AthGene internal API documentaion",
        "version": "1.0.0"
    },
    "host": "localhost:8765",
    "basePath": "/api",
    "schemes": [
        "http",
        "https"
    ],
    "consumes": [
        "application/json",
        "application/x-www-form-urlencoded"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/categories": {
            "get": {
                "tags": [
                    "Categories"
                ],
                "summary": "List of categories",
                "description": "Retrieves a list of categories indicating id, name and version of each category.",
                "parameters": [
                    {
                        "name": "Authorization",
                        "in": "header",
                        "description": "JWT token",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful operation",
                        "schema": {
                            "$ref": "#/definitions/categories/CategoryList"
                        }
                    },
                    "401": {
                        "description": "Not authorized"
                    },
                    "405": {
                        "description": "Only accepts get"
                    },
                    "500": {
                        "description": "Token verification failed"
                    }
                }
            }
        }
    },
    "definitions": {
        "categories/CategoryList": {
            "properties": {
                "categories": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/categories/CategoryShort"
                    },
                    "example": "List of all categories, with id, name and version"
                }
            },
            "type": "object"
        },
        "categories/CategoryShort": {
            "properties": {
                "id": {
                    "type": "integer",
                    "example": 1
                },
                "name": {
                    "type": "string",
                    "example": "Best category ever"
                },
                "version": {
                    "type": "integer",
                    "enum": [
                        1,
                        2
                    ],
                    "example": 2
                }
            },
            "type": "object"
        }
    }
}

The validator however throws errors like the following:

API Errors:

  #/paths/~1categories/get/responses/200/schema/$ref: Definition could not be resolved: #/definitions/categories/CategoryList
  #/definitions/categories~1CategoryList/properties/categories/items/$ref: Definition could not be resolved: #/definitions/categories/CategoryShort

API Warnings:

  #/definitions/categories~1CategoryList: Definition is defined but is not used: #/definitions/categories~1CategoryList
  #/definitions/categories~1CategoryShort: Definition is defined but is not used: #/definitions/categories~1CategoryShort

2 errors and 2 warnings

I, however, don't seem to get any errors when I codegen my client. Am I abusing the swagger def, or is this an issue with the validator tool? I've replaced the "/" with "." which works.

[whitlockjc]

The issues is due to you having / in the #/definition name. While Swagger itself does not forbid this, it does break JSON References resolution because / is a special character for JSON Pointers (https://tools.ietf.org/html/rfc6901#section-3).

I will keep this open and raise an issue on the OAI repository to see if they have a position on this. If they do not, I will update json-refs to address this.

[SAThomsen]

Sounds good! Sorry for the late reply @whitlockjc. I missed the notification.