using @Examples() on a model

[Romakita]

Discussed in https://github.com/orgs/tsedio/discussions/2631

^{Originally posted by VictoriqueMoe March 21, 2024}
hello.

I have the following decorator in my argument:

@QueryParams("expires")
@Examples({
	empty: {
		summary: "empty",
		description: "expires according to retention policy",
		value: "",
	},
	"1d": {
		summary: "1d",
		description: "expires in 1day",
		value: "1d",
	},
})
@Description(
	"a string containing a number and a letter of `m` for mins, `h` for hours, `d` for days. For example: `1h` would be 1 hour and `1d` would be 1 day. leave this blank if you want the file to exist according to the retention policy",
)
@Pattern(/^$|^\d+[mhd]$/)
customExpiry?: string,

this is a Parameter.

I like this because in swagger, you can get a dropdown of all the eamples

I am now moving all the @QueryParams to an model object to not pollute the class. my object looks as follows:

@Name("WaifuUploadParameters")
@Description("Upload parameters for put requests")
export class FileUploadParameters {
    @Description(
        "a string containing a number and a letter of `m` for mins, `h` for hours, `d` for days. For example: `1h` would be 1 hour and `1d` would be 1 day. leave this blank if you want the file to exist according to the retention policy",
    )
    @Pattern(/^$|^\d+[mhd]$/)
    @Property()
    public expires?: string;

    @Description(
        "if set to true, then your filename will not appear in the URL. if false, then it will appear in the URL. defaults to false",
    )
    @Property()
    public hide_filename?: boolean;

    @Description(
        "Set a password for this file, this will encrypt the file on the server that not even the server owner can obtain it, when fetching the file. you can fill out the `x-password` http header with your password to obtain the file via API",
    )
    @Property()
    public password?: string;

    @Description("Shh, it's a secret ;)")
    @Property()
    public secret_token?: string;
}

I want the examples to stay for expires. however the @Examples() decorator is only a ParameterDecorator and the non-plural version @Example() does not do the same thing, all that seems to do is fill in the input with a default value. not a dropdown like @Examples()

Is there a way so that the model can have Examples() and it renders in the swagger of a deropdown of examples?

[Romakita]

Solution

class QueryParamModel {
  @Property()
  path: string;

  @Property()
  condition: string;

  @Property()
  value: string;
}

@Path("/query")
class QueryModelCtrl {
  @OperationPath("GET", "/")
  async get(
    @QueryParams()
    @Examples({
      example1: {
        description: "description1",
        value: {
          path: "path1",
          condition: "condition1"
        }
      },
      example2: {
        description: "description1",
        value: {
          path: "path2",
          condition: "condition2"
        }
      }
    })
    q: QueryParamModel
  ) {}
}

Generates:

{
  "paths": {
    "/query": {
      "get": {
        "operationId": "queryModelCtrlGet",
        "parameters": [
          {
            "in": "query",
            "name": "path",
            "required": false,
            "examples": {
              "example1": {
                "description": "description1",
                "value": "path1"
              },
              "example2": {
                "description": "description1",
                "value": "path2"
              }
            },
            "schema": {
              "type": "string"
            }
          },
          {
            "examples": {
              "example1": {
                "description": "description1",
                "value": "condition1"
              },
              "example2": {
                "description": "description1",
                "value": "condition2"
              }
            },
            "in": "query",
            "name": "condition",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "value",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "tags": [
          "QueryModelCtrl"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "QueryModelCtrl"
    }
  ]
}

[github-actions]

🎉 Are you happy?

If you appreciated the support, know that it is free and is carried out on personal time ;)

A support, even a little bit makes a difference for me and continues to bring you answers!

[Romakita]

🎉 This issue has been resolved in version 7.66.0 🎉

The release is available on:

• v7.66.0
• GitHub release

Your semantic-release bot 📦🚀