redoc
redoc copied to clipboard
Redocly
Add x-immutable vendor extension
Hi - One of the issues we're running into with our API spec and API docs is around immutable properties. That is, a property that can be set on create (POST) but not updated later (via PATCH or PUT).
Today ReDoc shows immutable: true inside the "Request Body Schema" since I'm using an x-immutable: true vendor extension in my OpenAPI doc. However, what I'd really like is to just not show these properties in the Request Body Schema on PUT/PATCH at all.
Ideally this immutable attribute would be standardized by OpenAPI itself, but until that happens... vendor extensions are our next best bet.
One obvious alternative option is to use separate schemas, like FooCreate and FooUpdate but that doesn't work well with other tooling (e.g., SDKs from openapi-generator would end up with separate classes for each schema and lots of unnecessary boilerplate translation inside each client). This was the way we were using originally...
what I'd really like is to just not show these properties in the Request Body Schema on PUT/PATCH at all.
How do we know that the PUT is not creating a resource?
It seems there would need to be maybe a configuration map to define which http methods the immutability applies to...
@adamaltman Yeah, if we need a config map that would be ok by me. I know that some APIs use PUT for creation for idempotency.
If you don't want a boolean x-immutable, we could solve my problem a bit more generically with the extensions discussed here like x-createOnly, x-updateOnly, and so on...
@adamaltman Come to think of it, even if a field is immutable, it still has to be specified on PUT according to HTTP semantics of being an idempotent replacement, right? In this case, I think we only need this behavior on PATCH and won't need any additional configs.
Microsoft use x-ms-mutability property for that. See details at https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-mutability . Microsoft has solved the issue of parameters that can only be set when creating a resource.
