Document REST, Webhooks, WebSockets, gRPC API Reference

[dannysheridan]

What's the issue?

Missing content (not covered in the docs)

URL of the documentation page (if applicable)

No response

Describe the gap or issue

We support generating API References for multiple protocols, specifically:

• REST API
• Webhooks
• WebSockets
• Server-sent events
• gRPC

However we don't make it clear in the Docs documentation what these look like or how you configure them.

REST API -> powered by OpenAPI or Fern Definition. Example

Webhooks -> powered by OpenAPI or Fern Definition (need an example)

WebSockets -> powered by AsyncAPI or Fern Definition Example

Server-sent events -> powered by OpenAPI or Fern Definition (not in the OpenAPI spec, requires the fern-specific extension) Example

gRPC -> powered by protobuf (in development; can provide an example link via DM)

How should this be improved?

there's no place where a user can see that we support multiple protocols in our API reference. webhook reference is out of place standing alone in the rain. I imagine these pages would all live within a section.

Are you interested in contributing this docs improvement?

No, just reporting the issue.

Attach Files (Optional)

No response

[cwcowell]

@dannysheridan Don't see any reference to GraphQL in the docs, but double-checking that it's not currently supported?

[dannysheridan]

Confirming we do not support it. Would be fine mentioning that explicitly if you'd like! If someone does want it, they should open an issue.

[dannysheridan]

Webhook reference

1. The intro of the page re-explains the x-fern-webhook extension without linking to the original place it is documented (link)
2. On OpenAPI 3.1.x there is a native webhooks field that we support parsing that we don't acknowledge (this should be fixed on both places)
3. It would be nice to start this page off with a screenshot of a webhook reference may look like/why its worth having

[dannysheridan]

Documented AsyncAPI/WebSockets here: #6100

[cwcowell]

@dannysheridan Do we know of any client repos that use gRPC or Server-sent event APIs that I could use to see how to configure Fern to use those protocols?

I'm looking through GitHub for open source projects that use those protocols with Fern-generated docs, but no luck yet.

https://buildwithfern.com/learn/sdks/introduction/customer-showcase doesn't have examples I can use -- the listed customer GitHub repos don't include source files for their docs.