This is the back end analytics ReST API for accessing the information generated from the Carmageddon demonstration application.
The API documentation is located at: https://oci-labs.github.io/carma-api
The documentation is generated from an API blueprint (.apib) format markdown source located in this repository. The conversion of the APIB file to HTML is performed based on the 'blueprint-docify' GitHub project. That project includes calls to a node.js translator for the APIB markdown. The HTML documents are generated on Shippable.com. This is described below.
Automatic generation of API documentation is done when any commit is pushed to the GitHub repository for the API.
If the commit message includes the string:
[skip ci]
or the string:
[no-ci]
then the generation step will be avoided.
The hosted CI service from Shippable.com is used to actually execute the code generation and to push the results back to the GitHub pages for the repository.
The shippable.yml file in the repository causes a compilation script to run on Shippable.com that will generate the documentation from the source, then push it to the gh-pages branch on the repository.
Accounts, Organizations, and Repositories are needed on two different hosted services to accomplish the automatic generation of the API documentation.
GitHub is used to store the API source definitions that are used to generate the documentation. It is also used to host the documentation once it is generated by pushing the HTML documentation to the GitHub pages associated with the repository.
Shippable is used to perform the autogeneration steps by executing a script when a commit is made to the repository and then pushing the generated results back to the GitHub pages.
The API documentation and automatically generating the documentation requires several resources in GitHub.
In addition to a developer account for each committer to the API repository, an Organization is needed to contain the respository and allow the committers to collaborate. The Repository is created within the Organization with the committers added as team members with push privileges to it.
An additional GitHub account is created for the automated processing to use so that it can be segregated from the actual committers. The bot account is added as a public committer to the organization and the repository.
The resources used within GitHub include:
- Committer accounts
Each developer collaborating on the API should have their own account within GitHub. These accounts are added as public committers to the repository and organization.
- Autogeneration account
A new account dedicated to the autogeneration process is created on GitHub. To avoid creating a new account, this account can use Google's e-mail trick of adding a suffix in order to ensure a unique e-mail is used for registration. So, for example, a committer with the e-mail '[email protected]' could create a bot account using the e-mail '[email protected]' and the original committer will receive all e-mail to the bot while at the same time the uniqueness of the bot account e-mail is ensured.
This repository is using the account:
oci-labs-bot
as the autogeneration account.
- Organization
An organization is created to hold the repository. Each committer is added as a public member of the organization. The autogeneration account is also added as a public member of the organization.
This repository is contained in the organization:
oci-labs
- Repository
The repository for the API is created publicly in the organization. The committers, including the autogeneration bot, are added as committers to the repository.
This repository is
carma-api
- GitHub pages
The API documentation is made viewable on the GitHub pages associated with the repository. This is done by pushing the documentation to the orphan branch:
gh-pages
By default, the documentation will be available at the GitHub IO pages site for the repository:
http(s)://oci-labs.github.io/carma-api
A Shippable.com account for the API bot GitHub account was created, username:
oci-labs-bot
which has been authorized to access the repository for the API. This account will trigger a CI task to run when a post-commit hook in GitHub notifies it. This will execute a Node.js script that uses the aglio (https://github.com/danielgtaylor/aglio) conversion tool to generate an HTML version of the API. These results are then pushed to the gh-pages branch of the repository.