search

Redocly / redoc

📘 OpenAPI/Swagger-generated API Reference Documentation
https://redocly.github.io/redoc/
MIT License
22.88k stars 2.26k forks source link

Add x-immutable vendor extension #1290

Open codyaray opened 4 years ago

codyaray commented 4 years ago

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.

Screen Shot 2020-06-04 at 3 32 25 AM

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...

adamaltman commented 4 years ago

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...

codyaray commented 4 years ago

@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...

codyaray commented 4 years ago

@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.

adamaltman commented 4 years ago

That makes the scope clear. 👍 🎉

Thanks @codyaray!

ad-m commented 3 years ago

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.

codyaray commented 2 years ago

Still interested in this :)

spacedsweden commented 2 years ago

me too