Describe expected response times for responses

I can describe expected return codes, response types and even expected responses via the spec: https://swagger.io/docs/specification/describing-responses/

What I feel is missing right now is the ability to document expected response times. As a developer, I know my endpoint should return in <100ms with a 201.

Is there a way to achieve this today (perhaps via some custom annotation?) or would this require a spec update. If so, how do I formally submit that as a request?

[rafalkrupinski]

@agardnerIT OAS allows arbitrary extension fields so I don’t think you need to start a long process to change it for your particular needs.

How you support timeouts depends on your tooling. If you use a code generator to create the client code, you can add an extension field and handle it in the generator (You say you don’t want to fail the request, but I guess you’d add a warning).

If the client is coded by hand, you can either use an extension or simply the description field and let the client developer handle it in their code.

It’s also a matter of how you create the schema. If it’s generated from the server code, it also needs to support adding extension fields.

[agardnerIT]

My intention isn’t to fail the response but more use it as a hint. Ie. when the request hits the API to the backend and back - that’s the time I’m interested in hinting at.

Other actors can then infer expected behaviour. It would eliminate false callouts as I can see that actually, the dev intended it to take 5 seconds so no point in moaning that it is taking 3.