Home

Document your first API with GitHub Pages

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.

Requirements

• OpenAPI file with the definition of your API.

Steps

1. Fork the GitHub repository.
2. Go to the Options tab in your repository's Settings.
   1. 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].
   2. 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/).
3. Go to the Actions tab and select Enable to enable automated publishing of your site to GitHub Pages.
4. 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.
5. 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.

Customize the site

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.

Requirements

• 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.

Steps

1. Clone the forked repository to your local environment.
2. Launch the server.
   1. Open the command line and navigate to the catalog folder with the command cd catalog.
   2. Run npm install to resolve dependencies.
   3. Run npm start to start a local server.
3. Open http://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.
4. After making the changes, push them to your GitHub repository.
   1. Run git add -A to stage all changes.
   2. Run git commit -m "Commit message" to commit them.
   3. Run git push to push them to GitHub.
   4. 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.
5. After the GitHub Action completes, visit the published site at https://[username].github.io.

Advanced deployment options

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.