This repository has been archived by the owner on Jun 5, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 141
Home
Mike Budzynski edited this page Mar 30, 2021
·
5 revisions
GitHub Pages let you automate deployments of the API Portal and publish it to the Internet for free. Follow the steps below to publish documentation for your API with GitHub Pages.
- OpenAPI file with the definition of your API.
- Fork the GitHub repository.
- Go to the Options tab in your repository's Settings.
- Change the name of the repository to [username].github.io (replace
[username]
with your actual account name) for the site to properly load all the assets. The portal will be deployed under the URL https://[username].github.io, without a URL path suffix. If your repository is part of an organization and not under your individual account, use the organization name in the place of[username]
. - Scroll down to the GitHub Pages section. Select
gh-pages
as the source branch, leave the default root setting, and select Save. Copy the GitHub Pages URL (for example,https://contoso.github.io/
).
- Change the name of the repository to [username].github.io (replace
- Go to the Actions tab and select Enable to enable automated publishing of your site to GitHub Pages.
- Navigate to the
/api-specs
folder in your GitHub repository and drag-and-drop (or upload) an OpenAPI file. Provide a commit title and select Commit changes. - The GitHub Action will automatically trigger on the committed change and publish your website. Once it completes, visit the URL you copied in the step 2. (
https://[username].github.io
) to see the published API portal. You can check the GitHub Action status in the Actions tab of your repository.
Follow the steps below to customize the content of your API portal with the built-in drag-and-drop visual interface - edit or create pages, change styling, modify configuration, and more.
- Git on your machine. Install it by following this Git tutorial.
- Node.js (LTS version,
v10.15.0
or later) and npm on your machine. Follow this tutorial to install them.
- Clone the forked repository to your local environment.
- Launch the server.
- Open the command line and navigate to the
catalog
folder with the commandcd catalog
. - Run
npm install
to resolve dependencies. - Run
npm start
to start a local server.
- Open the command line and navigate to the
- Open
https://localhost:3000/admin
in a browser to access the administrative interface and make changes. Whenever you make a change, save it by selecting the save button (floppy disk icon) or pressing CTRL+S (Command+S on MacOS). Changes are saved into the/catalog/data/content.json
file. For instructions on customizations and overview of the interface, see documentation of the Azure API Management's developer portal. - After making the changes, push them to your GitHub repository.
- Run
git add -A
to stage all changes. - Run
git commit -m "Commit message"
to commit them. - Run
git push
to push them to GitHub. - GitHub Action will automatically trigger on the commit in the GitHub's repository. It will build and publish your website into the
gh-pages
branch.
- Run
- After the GitHub Action completes, visit the published site at
https://[username].github.io
.
You can also run the publishing step locally and deploy the generated static assets from the /catalog/dist/website
folder to the hosting solution of choice instead of GitHub Pages. To run the publishing step, execute the command npm run publish
on your local machine.