Search code examples
jsonapi-designswaggerswagger-ui

Override Verb Level Model/ Model Schema in Swagger-UI

I'm working with swagger-ui in an attempt to standardize API documentation. I realized that for verbs (GET, PUT, POST, etc.) which use a body parameter and therefore need to show a model and model schema, the schema is being defined at the resource level (/pet or /store in the pet store example). However, within our API, required body parameters are going to change from verb to verb, and it would be nice to have a model for each which accurately reflects this.

Current version of model definition in http://petstore.swagger.wordnik.com/api/api-docs/pet, where the model definition is like so:

swagger-ui-model-def

Is there any way to override the default resource-level model at the verb level?

Solution

  • In the swagger 2.0 spec, each of the resources has subsections for the HTTP methods (get, post, delete, etc). Each of these in turn has a parameters tag which maps to a list of JSON objects of the form below. In order for that body to use a separate schema, it can just be overridden using a schema tag and a $ref sub-tag, then referencing a definition you've provided separately in the definitions subsection at the bottom.

    {
    name: "body",
    in: "body",
    description: "set the properties of a pet",
    schema: {
        $ref: "#/definitions/PetPut"
    },
    required: true
}