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

7
ANSWERED

No discriminator support in Swagger

I used the `discriminator` feature of Swagger, in combination with `allOf` and `$ref` to create a form of polymorphism in my API spec. * Here's the documentation on the intended use of `discriminator` in Swagger specs: http://swagger.io/specification/#composition-and-inheritance--polymorphism--83 * And here's a more clarifying example: http://swagger.io/specification/#models-with-polymorphism-support-91 I use this in [my own spec](https://github.com/opentripmodel/opentripmodel/blob/master/api/swagger.yaml) a couple of times. It doesn't get rendered right in Readme.io's swagger implementation. The `discriminator` field is rendered as an ordinary text field, whereas it should be rendered as a drop down to select the desired sub type. Also, whenever a subtype is selected, the additional fields defined in that sub type should be rendered as well. Otherwise, there is no way to read the documentation of the sub types, let alone test them. The "Swagger UI" that is provided by the Swagger project itself, doesn't render this right either. However, the [Redoc](https://github.com/Rebilly/ReDoc) documentation template proves that it is perfectly possible to implement this. As a work around, I don't use Readme.io's Swagger support now, but link to a self-hosted website where I host a Redoc-rendered version of my API documentation. Needless to say that it would be much better if I could use Readme.io for this as well, enabling the creation of examples in different languages, Readme.io's excellent feedback options and of course the "try it" functionality, all of which I am missing in my current solution.

Posted by Bart Kummel 3 years ago

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 3 years ago