Consider authorization for OpenAPI request examples

[arredond]

It's very nice that Gitbook takes OpenAPI security schemes into account and shows them in OpenAPI blocks, but the code examples don't, which may cause significant confusion among users.

In this screenshot, I'd expect the code example to include something like -H "Authorization: Bearer $API_TOKEN".

Ideally, the "Try it" module would also have the specified authorization method pre-checked, though I recognize this is harder since you use an external provider for it.

[addisonschultz]

Nice suggestions - I'll relay to the team!

[arredond]

Any updates on this one? This remains as an odd sticking-point in our docs -- the OpenAPI code block clearly shows that BearerAuth is required as the only auth option, but the example Request code doesn't include it in the headers, which makes it much less useful (and even somewhat confusing) for our users

[addisonschultz]

We've still got an open ticket for this - trying to do a bit debugging and for more context on our side when we pick this up, I believe it's coming from this: https://github.com/GitbookIO/gitbook/blob/main/packages/react-openapi/src/OpenAPICodeSample.tsx#L134

Thanks for your patience on this one so far

[nolannbiron]

Hey @arredond, sorry for the delay, here's what I found

In your specification, it looks like both paths you provided in your screenshot don't have the security property. Is this intentional?

If you add the security property like this inside your paths, it will work with our updated OpenAPI blocks.

"security": [
    {
        "bearerAuth": []
    }
]

Some of your endpoints already have the security property (see example)

For the “Try it” feature, it displays available securitySchemes (even if they are not required for this endpoint). This is normal for testing the endpoint, but we won’t add it inside the block, as it could be misleading.

Let me know if you run into any other issues, happy to help!