temando / serverless-openapi-documentation

Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration
MIT License
93 stars 127 forks source link

Do we have support for Serverless AWS Documentation definitions? #51

Closed slatermorgan closed 6 months ago

slatermorgan commented 6 months ago

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.