Product Guide

ReadMe Documentation

Welcome to the ReadMe Documentation, where you'll find comprehensive guides and community support to help you start working with ReadMe as quickly as possible!

Get Started
Ask A Question

Questions

2
ANSWERED

Optional Fields In Swagger Import

Hi, First of all, want to say I'm really liking readme.io so far. Had a question about documenting optional request fields using a swagger import. We've successfully imported our swagger API specification, but are seeing some interesting behavior when viewing the documentation and the "Try it" feature. The request body for one of our api endpoints is a reference to ```json "Event": { "description": "", "properties": { "action": { "description": "", "type": "string" }, "actor": { "$ref": "#/definitions/Actor" }, "group": { "$ref": "#/definitions/Group" }, }, "required": [ "action" ], "type": "object" } ``` Many of the fields, like `group` and `actor` are market as optional, but they have a field `id` that is marked as required: ```json "Group": { "description": "", "properties": { "id": { "description": "", "type": "string" }, "name": { "description": "", "type": "string" } }, "required": [ "id" ], "type": "object" } ``` Since `group` itself is optional, we only want to require `group.id` if a `group` is passed: - A client not sending `group` at all is okay. - A client from sending *only* `group.name` and not `group.id` is not okay However, the generated documentation in readme.io seems to require `group.id` for the "Try It" feature. Does readme support these sort of "conditionally required" fields? Technically a valid request would be just ``` { "action": "some.action" } ``` but right now it is impossible to send such a request using the readme UI. Thanks for reading, I know that was a lot, and thanks in advance for any support on this. Dex

Posted by Dexter Horthy 2 years ago