Support for Swagger docs with ref objects inside of properties

[dspeele]

We have Swagger json for end points that return more complex documents (objects inside of objects). This is represented with references inside of properties objects. Here is an example Swagger document that shows what we need:

{
    "swagger": "2.0",
    "info": {
        "title": "Inventory API",
        "description": "API to retrieve inventory information",
        "version": "1.0.0"
    },
    "host": "api.company.com",
    "schemes": [
        "https"
    ],
    "basePath": "/v3",
    "produces": [
        "application/json"
    ],
    "paths": {
        "/inventory/product/{product_code}": {
            "get": {
                "summary": "Product Inventory",
                "description": "This end point takes a master product code and returns back the inventory for all variations of the master product.",
                "parameters": [
                    {
                        "name": "product_code",
                        "in": "path",
                        "description": "The product code for the master product.",
                        "required": true,
                        "type": "string"
                    }
                ],
                "tags": [
                    "Inventory"
                ],
                "responses": {
                    "200": {
                        "description": "An Object with request, response, and error information. If successful the response will contain a body with inventory information for each of the variations for the master product.",
                        "schema": {
                            "$ref": "#/definitions/Response"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Body": {
            "properties": {
                "body": {
                  "type": "string"
                }
            }
        },
        "Request": {
            "properties": {
                "body": {
                    "$ref": "#/definitions/Body"
                },
                "this_url": {
                    "type": "string"
                },
                "help": {
                    "type": "string"
                },
                "server_received_time": {
                    "type": "string"
                }
            },
            "required": [
                "body",
                "this_url",
                "help",
                "server_received_time"
            ]
        },
        "Variant": {
            "properties": {
                "upc_code": {
                    "type": "string"
                },
                "on_hand": {
                    "type": "integer"
                },
                "on_order": {
                    "type": "integer"
                },
                "ignore_inventory": {
                    "type": "boolean"
                },
                "ready_for_sale": {
                    "type": "boolean"
                },
                "store_on_hand": {
                    "type": "integer"
                },
                "find_in_store_on_hand": {
                    "type": "integer"
                }
            },
            "required": [
                "upc_code",
                "on_hand",
                "on_order",
                "ignore_inventory",
                "ready_for_sale",
                "store_on_hand",
                "find_in_store_on_hand"
            ]
        },
        "Result": {
            "properties": {
                "variants": {
                    "items": {
                        "$ref": "#/definitions/Variant"
                    },
                    "type": "array"
                }
            },
            "required": [
                "variants"
            ]
        },
        "Inventory": {
            "properties": {
                "help": {
                    "type": "string"
                },
                "messages": {
                    "$ref": "#/definitions/Messages"
                }
            },
            "required": [
                "help",
                "messages"
            ]
        },
        "Message": {
            "properties": {
                "text": {
                    "type": "string"
                },
                "code": {
                    "type": "string"
                }
            },
            "required": [
                "text",
                "code"
            ]
        },
        "Messages": {
            "properties": {
                "product": {
                    "items": {
                        "$ref": "#/definitions/Message"
                    },
                    "type": "array"
                }
            }
        },
        "Error": {
            "properties": {
                "inventory": {
                    "$ref": "#/definitions/Inventory"
                }
            }
        },
        "Response": {
            "properties": {
                "request": {
                    "$ref": "#/definitions/Request"
                },
                "response": {
                    "$ref": "#/definitions/Result"
                },
                "errors": {
                    "$ref": "#/definitions/Error"
                }
            },
            "required": [
                "request",
                "response",
                "errors"
            ]
        }
    }
}

Running apidoc, I can see that support for this is a TODO (Field.scala line 105). Stepping through your tests (nice work, btw!) I can see that the swagger parser parses our document properly but additional coding is needed to move this into apidoc world. I'd very much like to work on this but it would be nice to do a bit of planning first to make sure I'm on the same page with you about how to add this functionality in.

Regards,

Dana

[mbryzek]

Thanks! I've started a branch:

353-swagger-refs

which contains this example json in it.

I'll also need to do a bit of work to learn how the ref is mapped internally in swagger to figure out appropriate lookup for apidoc. In general, hoping the solution is to look up the reference and then recurse with a call to to Field.apply()

[dspeele]

This is blocked by #356. Please have a look at my pull request.

[chrishough]

Do we know when the fix to support $refs is going in?

[mbryzek]

@chrishough openapi support has been community driven and is not currently under active development

[chrishough]

@mbryzek bummer, so are there plans to build a variation of ref like linking in the API Builder Specification?

[mbryzek]

@chrishough no plans. API Builder has the concept of a template which makes it possible to avoid duplication - those are working well that at this point I have not seen a gap for what we would otherwise solve with $ref in OpenAPI

API Builder's approach is conceptually like a type system for your API and that heavily influences what features we add into api builder over time.

I'm personally curious as to what problem you see in api builder that $ref would solve

[chrishough]

@mbryzek I have used the JSON Schema specification extensively for enterprise APIs, and now that the OpenAPI specification basically consumed the JSON Schema specification with Swagger, I am comparing the API Builder specification against the OpenAPI specification.

With well over 500 models, and even more request shapes in my past REST APIs we utilized $refs and deep linking to DRY up and organize our schemas against the specification. This kept our code both organized and easy to test. In turn, beyond $refs we utilized the AdditionalParameters false setting in the specification so tests failed if new attributes were added and not properly accounted for in schemas. I do believe API Builder supports that feature, just not $refs.

Our core schemas were organized as shown:

• models/**/*
• requests/**/*
• shared/**/*

The models basically matched the database attributes, but the requests + shared defined the contracted shapes to the FE.

[chrishough]

@mbryzek did you have thoughts on this?