Is this Serverless AWS Documentation reference syntax supported?

[slatermorgan]

If you read the Serverless AWS Documentation or any of its more maintained forks, it mentions that you can reference a model using the following syntax.

custom:
  documentation:
    models:
      -
        name: "Address"
        description: "This is an address"
        contentType: "application/json"
        schema:
          type: "object"
          properties:
            street:
              type: "string"
      -
        name: "Customer"
        description: "This is a customer"
        contentType: "application/json"
        schema:
          type: "object"
          properties:
            name:
              type: "string"
            address:
              $ref: "{{model: Address}}"       <--------------

I keep getting
-attribute components.schemas.Customer.{{model: Address}} is not of type schema

Is the syntax $ref: "{{model: Address}}" supported in this plugin?

I notice that the example petstore OAS uses the syntax:
$ref: '#/components/schemas/ProductsProduct'

Should I move my references so they look more like this?

The problem is the models in my custom.documentation block of my serverless.yml stack are used for the Serverless AWS Documentation plugin, however if I use this plugin on the same serverless.yml, I keep getting invalid OAS specification (because the models contains these {{ }} type references.

[JaredCE]

Unfortunately there isn't an overlap as yet. Even the OAS syntax of $ref: '#/components/schemas/ProductsProduct' isn't supported just yet.

i think it's going to take me a bit of a rewrite and upgrade to OpenAPI 3.1.0 generation to get models in a really good resusable space.

[slatermorgan]

just to confirm, does this not support splitting models into multiple files at all?

[JaredCE]

it does, but maybe not how you like. Take this for example:

custom:
  documentation:
    ...
    models:
      - name: AlternativeResponse
        content:
          application/json:
            schema: ${file(./models/alt.json)}

Then within alt.json you have:

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "name": {
      "type": "string"
    },
    "lastname": {
      "$ref": "/Users/jaredCE/Projects/GitHub/Personal/serverless-openapi-documenter/test/serverless-tests/best/models/alt2.json"
    }
  }
}

and in alt2.json it's like:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "lastname": {
      "type": "string"
    }
  }
}

it will pull together the schemas and generate:

"AlternativeResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "lastname": {
            "type": "object",
            "properties": {
              "lastname": {
                "type": "string"
              }
            }
          }
        }
      },

[slatermorgan]

Hmm actually might work for my edge-case, given I can use a relative path there instead of absolute