Additions to API References

Feature Discussion
#1

Hola!

We’ll be focussing the upcoming weeks on resolving bugs and adding features to the API References section.

On our roadmap:

  • Support for examples. :white_check_mark:
  • Support for parameters under path
  • Support for showing Authentication headers in example request :white_check_mark:
  • Support for showing response headers :white_check_mark:
  • Bug fix for Request Schema Object title not showing :white_check_mark:
  • Support for more libraries &frameworks. :construction_worker_man:
  • Faster API Reference rendering for big API References :white_check_mark:

Can you please opt in to more changes that are needed?

Also, which libraries & frameworks do you require?

#2

All those changes sound great, thanks Zaid!

#3

One point to add… last week I tried to add an image in the main description of the API, and it displayed, but it didn’t resize at all. If you could have a look at that or let me know what I was doing wrong, that would be great.

#4

Unfortunately we do not support image sizing through Markdown, so you would have to do it in HTML as such:

<img src="https://res.cloudinary.com/developerhub/image/upload/v1585411812/1/nvoec1irpjoze3iqzrso.svg" width="100"></img>

You can add that in the description fine.

#5

We were using HTML, just that it was a large image. As you mentioned to me over email, setting width=100% in the img tag sorts it (and don’t use style as it gets removed). Thanks!

#6

Alright wow, so lots of changes so far:

  • Requests

    • Support for example under oneOf,anyOf,allOf.
    • Support for showing the first example of examples.
    • Bugfix: Object title was not shown.

  • Responses

    • Support for all examples, where you can select which one to see.

  • For Requests and Responses

    • When an array has undefined items type, we wouldn’t show “undefined” anymore. We would show just “array”.

  • For Markdown rendering

    • Images over 100% size will not overflow the container anymore.

@Adam_Garrod this should cover all the features and bugs you have reported, except for the ability to choose an example parameter.

#7

A few requests from me :slight_smile: :

  1. Automatically display the headers of the security scheme used for an endpoint - without having to manually add it each time.
  2. Properly parse the parameters on the endpoint level and not only on the endpoint/method level.
  3. Use the header description as the value in the code examples (show X-API-KEY:{ your-api-key} instead of X-API-KEY: {X-API-KEY})
  4. Add code examples for C#, Java, Ruby, Golang, and PHP :grin:
  5. Use tabs in the code “Example Response” section, similar to the text section
  6. Make the request/response code section stick to the top as long as the request/response in text section is in view

I can come up with more ideas if you’d like :slight_smile:

Ran

#8

@zed, amazing work as always.

For the “title” fix, it shows the text which is great, but would it be possible to support HTML in there like “description”. It’s just that we want to put some badges there to show the direction of the requests/responses as incoming/outgoing.

See screenshot attached.

Badges
Badges1864×1536 184 KB

#9

@Adam_Garrod title is not defined in OpenAPI Spec to be CommonMark Syntax compatible. Is it possible to only keep the description HTML enabled for your use case as you showed in the screenshot?

#10

@zed, I’ll just keep it in description then if title doesn’t support it . Thanks for checking!

#11

Just tested this - 99% works. You need to remove the value key as each example’s code should reside inside a value key:

"examples": {
    "My Example": {
        "value": {
            // example code goes here
        }
    }
}
#12

Ah you are totally right.

You need to remove the value key as each example’s code should reside inside a value key

Will get that fixed later today.

1 Like
#13

@Ran_Aroussi

Add code examples for C#, Java, Ruby, Golang, and PHP :grin:

can you be more specific about what libraries/frameworks to show for C#/Java/Ruby/Golang/PHP?

There are so many libraries for each one of these languages, and I do not believe that for PHP you might want to show raw CURL PHP functions, but rather use Guzzle for example?

#14

Golang → net/http
PHP → Guzzle/CURL
C# → HttpClient
Java → Apache HTTPClient
Ruby → net/http

Also - since Node.js “request” has been deprecated, it would be great to use axios in the examples instead.

#15

You need to remove the value key as each example’s code should reside inside a value key

This is fixed now

Golang → net/http
PHP → Guzzle/CURL
C# → HttpClient
Java → Apache HTTPClient
Ruby → net/http

Goland net/http and PHP Guzzle are now available.

1 Like
#16

@zed - fastest service ever! :rocket:

#17

Just a quick note - I noticed that with Golang, the examples are always using GET - regardless of the method :wink:

1 Like
#18

That’s been fixed. Thanks!

#19

Perfect.

However - I just noticed that non of the code snippets is sending the payload/request body…

#20

@zed - Found a bug… The object key name is taken from the ref name instead of the object name when the object is array of refs

Screen Shot 2021-02-04 at 17.35.50
Screen Shot 2021-02-04 at 17.35.501868×834 145 KB