556d0a6239
What: Swagger UI has bad-UI and extensibility. It's not intuitive and often displays information badly (especially for more complicated structs), which leads to initial API confusion. How: Switch over to use Rapidoc. This is our new api docs! Created the airbyte-public-api-docs bucket and uploaded our new html docs. Set up a CloudFront distribution to enable HTTPS. A copy of our html docs is checked in in this PR. As you can see, this is a minimal file that relies on a React component published by Rapidoc. It is pointed to the api docs in our master branch and will automatically update itself; do not expect us to need to touch this api file unless we want to make display changes. I consolidated all files involving api documentation into the docs/api folder for simplicity. I also moved the generated html file to the generated-api-html folder within the api folder to make it clear it was generated. Finally, added a README to document our set up. Benefits: UI is much cleaner. We control the html source file, which means it'll be easier for us to make changes in the future.
882 B
882 B
API Documentation Folder
generated-api-html: Plain HTML file automatically generated from the Airbyte OAS spec as part of the build.api-documentation.md: Markdown for API documentation Gitbook page.rapidoc-api-docs.html: HTML for actual API Spec Documentation and linked to in the above Gitbook page. This is a S3 static website hosted out of theairbyte-public-api-docs bucketwith a Cloudfront Distribution for SSL. This file points to the Airbyte OAS spec on Master and will automatically mirror spec changes. This file will need to be uploaded to theairbyte-public-api-docsbucket for any file changes to propagate.