swagger path $ref for OPTIONS requests - swagger

Question

I want to construct an API gateway deployment from a swagger.yml file. I need to support CORS for all endpoints. All my options path definitions are exactly the same. How do I define the options path one place and $ref it where I want to use it?
I was hoping to do something like this (note the $ref: '#/definitions/CorsOptions' at the same level as get):
---
swagger: "2.0"
info:
version: "2016-10-26T03:15:31Z"
title: "corstest"
host: ""
basePath: ""
schemes:
- "https"
paths:
/page:
get:
produces:
- "application/json"
responses:
200:
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
uri: "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:1234:function:myLambdaFunc/invocations"
passthroughBehavior: "when_no_match"
httpMethod: "GET"
type: "aws_proxy"
$ref: '#/definitions/CorsOptions'
definitions:
Empty:
type: "object"
title: "Empty Schema"
CorsOptions:
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
Cache-Control:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "when_no_match"
type: "mock"
This yaml does not pass swagger validation. How can I pull off what I'm trying to do so my yaml file is not huge and bloated with the same options path definition.
The swagger spec supports $ref as a path item object however I can't figure out where I can put that definition of the path item object. I think API Gateway swagger import restricts pulling yaml files from other places but I'm not 100% sure.

Answer 1

I don't think that will work. API Gateway currently only supports $ref for models and schemas, not for arbitrary objects. We have a backlog item to support $ref in more places, so we might add support for this eventually.

Answer 2

If you would like to specify $ref values in arbitrary places, you can use the expand-swagger-refs module.
This will take a Swagger schema as an input, and automatically inline all your $ref values, giving you back a schema that is suitable for use with API gateway.
It is available on the command line with support for stdin and stdout:
swagger-expand < my-complex-schema.json > aws-compatible.json
And also as an importable Node module:
const { expand, expanded } = require('expand-swagger-refs');
const schema = require('./api/swagger.json');
// Create a copy of the schema, with $ref values expanded:
const expandedSchema = expanded(schema);
// Or expand the schema object in-place (mutates the object):
expand(schema)