search

stoplightio / desktop

The Stoplight desktop app + issues repository.
https://stoplight.io
79 stars 13 forks source link

`readOnly` schema field not respected in generated documentation #207

Open rossmcdonald opened 6 years ago

rossmcdonald commented 6 years ago

The readOnly field referenced in the OASv2 specification does not appear to be respected when converting a spec to API documentation. Per the spec:

This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request.

So anything with a readOnly option set to true should not be displayed in the API request documentation, only the response.

As a workaround to this issue, the same effect as readOnly (and writeOnly, which was added with OASv3) can be accomplished by using the Stoplight CRUD Builder (the "CRUD" button in the Next UI) and marking objects as read-only and write-only. Since the CRUD builder generates models via pure object modeling, read-only and write-only properties can be created that way.

jayshao commented 5 years ago

This would save a lot of editing complexity for my teams - much of the proliferation of model variations and inheritance is to allow for "system assigned" fields like id, created_on timestamps, etc.

erik-hansen commented 5 years ago

The proposed workaround produces separate models rather than nicely leveraging the spec to have a single model. Your rendered docs display "readOnly" as a validation when true, but the field should be hidden/removed completely and not added to the "Send Test Request" body. image

Also, the schema editor does not have a "readOnly" toggle. I have to go to "source" to add the boolean manually.

voxelbustersold commented 5 years ago

May I know when there will be an option for readonly flags?