Understanding of relationships between objects in a swagger document

[Andrew Popov]

Hello,

I am setting up two models schemas with "one way embedding". Here is the simple example "Books" and "Categories"

In Mongoose that's how my schemas looks like:

var BookSchema = new Schema({
    name: {
        type: String
    },
    category: [{
        type: mongoose.Schema.Types.ObjectId,
        ref: 'Category'
    }]  
});

var CategorySchema = new Schema({
    name: {
        type: String
    }
})

Now in OpenAPI (Swagger 2.0) JSON schema I figured 'definitions' must be the following in order to make reference work:

...
"definitions" : {
    "Book" : {
        "type": "object",
        "properties" : {
            "name" : { 
                "type": "string"
            },
            "category" : {
                "type": "array",
                "items": {
                    "_mongoose" : {
                        "type" : "objectId"
                    },
                "$ref" : "#/definitions/Category"
                }
            }
        }
    }

    "Category" : {
        "type" : "object",
        "properties" : {
            "name": {
                "type": "string"
            }
        }
    }
}

Using such "definitions" I can do Book.aggregate and Book.populate <- with Categories.

Questions:

1. Is this correct approach or am I missed something ?
2. If correct, then property "_mongoose" creates non-standard type "objectId" ? (MongooseSpecific)
   Is there other ways more elegant ways how to solve that or this is the only way ?

My ultimate goal is to create generic schema with ability to perform "aggregate" and "populate" using "one way embedding".

My apology in advance if there is some inaccuracy or misunderstand from my side on this topic but your further clarifications will be extremely helpful and I think beneficial for others.

Thank you very much.

Best Regards,
Andrew

[Mikael Nakajima]

I would also like to know the correct way to specify Mongo object relations via OpenAPI spec.

[Brian Anderson]

@andrejp Sorry for the delayed response here.

To my knowledge there is no way to specify Mongo object relations via the provided OpenAPI spec which is why this library takes advantage of the custom x- property definition as defined here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#patterned-objects

To answer the question above I may do something like this:

...
"definitions" : {
    "Book" : {
        "type": "object",
        "properties" : {
            "name" : { 
                "type": "string"
            },
            "category" : {
                "type": "array",
                "items": {
                    "type": "string"
                    "x-swagger-mongoose": {
                        "$ref": "#/definitions/Category"                
                    }
                }
            }
        }
    }

    "Category" : {
        "type" : "object",
        "properties" : {
            "name": {
                "type": "string"
            }
        }
    }
}

By specifying the relationship like this, your definition will show up in your swagger-ui as a property that takes a 'string' (namely an objectId) but behind the scenes when compiling the schemas via swagger-mongoose, the relationship is set up allowing for your desired aggregate and populate functionality

Let me know if that answers your question or if I misinterpreted something

[Brian Anderson]

closing for now.. let me know if more definition is needed