using @Examples() on a model

[VictoriqueMoe]

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?

[VictoriqueMoe]

FYI, this PR on my application is for this change for additinal context waifuvault/WaifuVault#131

[Romakita]

It’s fixed @VictoriqueMoe
See #2633

[VictoriqueMoe]

hm, i see it, but not really sure how to apply that to mine? I see @Examples is not on the model, how does the @Examples on the paramater know it would be for expires in the model?

This is my method:

@Put()
@Returns(StatusCodes.CREATED, FileUploadResponseDto).Description("If the file was stored successfully")
@Returns(StatusCodes.BAD_REQUEST, DefaultRenderException).Description("If the request was malformed")
@Returns(StatusCodes.OK, FileUploadResponseDto).Description("If the file already exists")
@Returns(StatusCodes.UNSUPPORTED_MEDIA_TYPE, DefaultRenderException).Description(
	"If the media type of the file specified was blocked",
)
@Example({
	description: "foo",
	summary: "bnar",
})
@Summary("Upload a file or send URL")
@Description(
	"Upload a file or specify URL to a file. Use the location header in the response or the url prop in the JSON to get the URL of the file",
)
public async addEntry(
	@Req() req: Request,
	@Res() res: Response,
	@QueryParams() params: FileUploadParameters,
	@MultipartFile("file") file?: PlatformMulterFile,
	@BodyParams("url") url?: string,
): Promise<unknown> {}

and my model:

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 examples for expires how using the example you gave? am i being dumb?
the examples would be

@Examples({
	empty: {
		summary: "empty",
		description: "expires according to retention policy",
		value: "",
	},
	"1d": {
		summary: "1d",
		description: "expires in 1day",
		value: "1d",
	},
})

I see you did

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
  ) {}
}

but what Property does that example get applied to and how does it know what one?

This is what my method USED to look like when it worked:

@Put()
@Returns(StatusCodes.CREATED, FileUploadResponseDto).Description("If the file was stored successfully")
@Returns(StatusCodes.BAD_REQUEST, DefaultRenderException).Description("If the request was malformed")
@Returns(StatusCodes.OK, FileUploadResponseDto).Description("If the file already exists")
@Returns(StatusCodes.UNSUPPORTED_MEDIA_TYPE, DefaultRenderException).Description(
	"If the media type of the file specified was blocked",
)
@Example({
	description: "foo",
	summary: "bnar",
})
@Summary("Upload a file or send URL")
@Description(
	"Upload a file or specify URL to a file. Use the location header in the response or the url prop in the JSON to get the URL of the file",
)
public async addEntry(
	@Req() req: Request,
	@Res() res: Response,
	@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,
	@QueryParams("hide_filename")
	@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",
	)
	hideFileName?: boolean,
	@QueryParams("password")
	@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",
	)
	password?: string,
	@MultipartFile("file") file?: PlatformMulterFile,
	@BodyParams("url") url?: string,
	@QueryParams("secret_token") @Description("Shh, it's a secret ;)") secretToken?: string,
): Promise<unknown> {}

as you can see it knows that @Examples is for expires

[VictoriqueMoe]

Would it be

@Examples({
	empty: {
		summary: "empty",
		description: "expires according to retention policy",
		value: {
                   expires: ""
                 }
	},
	"1d": {
		summary: "1d",
		description: "expires in 1day",
		value: {
                      expires: "1d"
                }
	},
})

?

[Romakita]

You have to write an object on the value field. Ts.ED will pick the value from examples[].value depending on the property displayed in the documentation.

Example:

@Examples({
	empty: {
		summary: "Expires: empty",
		description: "expires according to retention policy",
		value: {expires: ""},
	},
	"1d": {
		summary: "Expires: 1d",
		description: "expires in 1day",
		value: {expires: "1d"},
	},
})

You can have multiple examples that cover one or more properties (now):

@Examples({
	empty: {
		summary: "Expires: empty",
		description: "expires according to retention policy",
		value: {expires: ""}, // apply this example for expires
	},
	"1d": {
		summary: "Expires: 1d",
		description: "expires in 1day",
		value: {expires: "1d", secret_token: "new value"}, // apply this example for expires and secret_token
	},
})

See you :)

[VictoriqueMoe]

Perfect! you are the best!