search

Nexmo / nexmo-oas-renderer

Render your API references, Nexmo-style!
https://developer.nexmo.com/api
MIT License
45 stars 4 forks source link

Examples support #90

Closed mheap closed 3 years ago

mheap commented 3 years ago

This PR adds support for examples when viewing response bodies. See the sample Verify spec to see it live

Examples must be added at the media type level, alongside schema and an x-errors key must be added inside schema indicating which errors are used by that schema

image

lornajane commented 3 years ago

oh ... my. I was just on the phone to @tbedford to try to work out alternatives to this since we didn't have it half an hour ago!

mheap commented 3 years ago

It still needs work to decide how to show structure (oneOf) vs examples, but this is a start

mheap commented 3 years ago

After a chat in the APIs you won't hate Slack it looks as though the best option is to add examples at the schema level.

I'll put together a sample spec that uses this, and update the PR later in the week

mheap commented 3 years ago

Adding examples at the schema level rather than the media level solves our oneOf problem I think. The review app has been updated to show the examples as a dropdown for each oneOf structure.

I think this is ready for review

https://nexmo-oas-renderer-pr-90.herokuapp.com/vonage/verify#verifyRequest

lornajane commented 3 years ago

Sorry for the slow response on this! So I'm looking at the schema example (ref http://spec.openapis.org/oas/v3.0.3.html#model-with-example) and in that context, examples can only contain the thing, not the extra fields like "summary". so we can show just what would be in values - I think a minor structure change. (for comparison, and so I can find this again, here are the docs for using examples in a response object http://spec.openapis.org/oas/v3.0.3.html#media-type-examples).

One big downside of rendering it from schema rather than from response as we already have in Verify API is that tools beyond our own don't seem to recognise it. For example: Redoc renders the examples in the current version of Verify API in its docs (I didn't check Stoplight yet but that would be good to know as well), and Prism doesn't recognise this example format either so we might need an alternative tool for user sandboxes.

lornajane commented 3 years ago

More discussion while I can remember what I've just read! There's a great post about examples here https://phil.tech/2020/openapi-examples/ and the discussion @mheap had on APIs You Won't Hate slack is also valuable. What I took from it is: the way Verify has it (currently, so v1.1.3 rather than the one in this PR) is the best supported of the lot and the least-worst option, but not everyone recommends having examples for every possible response from the API (in the example of Verify which does not use status codes I think the examples have more application but it's a good point). However we have a bunch of APIs where each endpoint can return more than one shape of thing, and we use the oneOf keyword inside schema to describe each structure. There isn't really a good way to have per-oneOf examples, so all the examples would be grouped together and the user would have to choose which oneOf thing they want the field details for and then also choose the right example to view as well - which I think is what this PR tries to avoid and how we ended up here.

mheap commented 3 years ago

Proof of concept is ready at https://nexmo-oas-renderer-pr-90.herokuapp.com/verify#verifySearch

Sample spec at https://github.com/Nexmo/nexmo-oas-renderer/pull/90/files#diff-92bd543c1abfb8eb6209982a67fa81988c428cb7a65d8a59bcd12ac0d9e71634R1129

@lornajane @marklewin @dragonmantank Is this how you expected it to work after our call?

marklewin commented 3 years ago

@mheap It looks great. When there are multiple error examples present though, I'd prefer if it didn't choose one to show me (which l assume is the first error listed in the spec?), because at a quick glance it might look like the only possible error.

Perhaps put some placeholder text in the dropdown that says "Select error type" and then only render an error once one has been selected?

Proof of concept is ready at https://nexmo-oas-renderer-pr-90.herokuapp.com/verify#verifySearch

Sample spec at https://github.com/Nexmo/nexmo-oas-renderer/pull/90/files#diff-92bd543c1abfb8eb6209982a67fa81988c428cb7a65d8a59bcd12ac0d9e71634R1129

@lornajane @marklewin @dragonmantank Is this how you expected it to work after our call?

mheap commented 3 years ago

@marklewin Yep, it shows the first one available. It looks strange without showing a response body there (I tested whilst building the feature) but agree that it could be missed. Any alternative ideas how to draw people's attention to it?

marklewin commented 3 years ago

@mheap How about some text above the dropdown that says "This endpoint can return more than one error. Select error type:" ?

mheap commented 3 years ago

@marklewin Let's review how to make it more obvious in a separate PR. There are teams dependent on this rendering to start building out specs