Add API reference

[maxrake]

Overview

As we migrate away from Readme.com, we may need a Phylum API reference on the new Phylum doc site.

Specifically, customers have found the code snippets from Readme.com to be very useful. Here is an example:

Additional context

There are at least two options that Docusaurus advertises in their Community Features section

• redocusaurus - A Docusaurus preset for integrating OpenAPI documentation into your docs with Redoc
• docusaurus-openapi-docs - A Docusaurus v2 plugin and theme for generating interactive OpenAPI docs

[kylewillmon]

It would be nice if the Phylum API reference existed on the main Docusaurus hosted site.

Why would this be nice? What benefit are we trying to get here over just a link to swagger?

[maxrake]

Why would this be nice? What benefit are we trying to get here over just a link to swagger?

The idea with this issue was to maintain parity between the current Readme.com site and the new Docusaurus one. The current site has an API Reference section that is integrated into the same website instead of sending users to api.phylum.io and appears to be more approachable than Swagger...with code snippets for many different languages.

That last point is subjective but also the best guess for why it was added in the first place (CC: @furi0us333). Maybe things have changed or the new doc site does not need anything more than a link to Swagger. Maybe this issue should be low priority and pushed off until there is more of a clear need for implementing it.

[louislang]

The readme deployment has the API docs, but it also provides code snippets to the user that the swagger docs don't. I can say from experience that customers use these snippets. It'd be very nice to continue providing this to them.

[kylewillmon]

Sounds good. I've updated the description of this issue to focus on code snippet examples.