README.md

OpenAPI & AsyncAPI example files

This directory holds OpenAPI & AsyncAPI example API contract files for standalone APIs and API Hubs which are deployed to bump.sh to generate elegant and always up-to-date API documentation.

View example standalone API contract files and generated documentation

You can find all available examples of OpenAPI and AsyncAPI API contract files in the apis folder of this repo

View example API Hubs and generated documentation

You can find all available examples of Hubs (or API Portals) of OpenAPI and AsyncAPI API contract files in the hubs folder of this repo

What are these API contract files?

Most of them are publicly available API contract files from real tech companies and products. Bump created and owned API contract files are:

• Bump is Bump.sh publicly available API
• My train Company is Bump.sh publicly available demo and has its live generated documentation available here.

How to contribute?

1️⃣ First, fork this repository and pull it on your local machine. 2️⃣ Create a new branch with git checkout -b <branch-name>.

I want to add a new standalone API specification file

3️⃣ Create a new file under ./apis/. Follow this file naming convention:

<bump-doc-slug>-[openapi|asyncapi]-source.[json|yml]

bump-doc-slug must be replaced by your api name with hyphens instead of spaces.

4️⃣ git add <path/to/file> your new API specification file content and git commit the file to your new branch. 5️⃣ git push origin <branch-name> from your new branch and create a new pull request in this repo. 6️⃣ In the pull request description add a link to the public source of the file.

I want to update standalone API or Hubs specification files

ℹ️ The only edits allowed are updates of the public specification files to reflect more up-to dates versions of the API contracts.

3️⃣ Locate the file you would like to edit under ./apis/ if Standalone API or under ./hubs if an API portal and proceed with updating the documents. 4️⃣ git add <path/to/file> the updated API specification files and git commit the files to your new branch. 5️⃣ git push origin <branch-name> from your new branch and create a new pull request in this repo. 6️⃣ In the pull request description add a link to the public source of the files.

Note to maintainers on new APIs specification files

In order for the files to be deployed automatically, we must create a new Documentation or Hub in the Bump demo organization. The Bump documentation slug must be the same as in the new file name following this naming convention: <bump-doc-slug>-[openapi|asyncapi]-source.[json|yml]. We also need to add a Bump.sh token in the .github/workflows/bump.yml file. The variable key name needs to be of the form <BUMP_DOC_SLUG>_BUMP_TOKEN. Then add the token value in the GitHub secrets of the current repo.