Seamlessly Integrate Gravitee API Documentation with GitHub

On the documentation page, go to ‘Import multiple files’

This will give you the option to import files from various sources like bitbucket, git, gitlab, github or any publicly accessible url. You can choose here if you want to immediately publish the files to the portal or only import them to the Manager and publish them manually later.

To refresh the documentation from the source you can either use the ‘Fetch All’ button on the ‘Documentation’ tab or make use of the ‘Auto fetch’ feature while configuring the external source. If you use the ‘Auto fetch’ feature you have to specify the frequency of updates in crontab format.

To import multiple pages there are 2 options:

• import all files in a specific directory
• use a gravitee descriptor file to import specific files in the directory and expose them in a structured way

For this blog we are going to explore the second option and use a gravitee descriptor file. This file needs to be named .gravitee.json and you must enter this file or its directory when configuring the import.

In this file you will list the files you want to publish on the portal and how you want them to be structured.

Example:

These are the files present on github:

After configuring this directory and executing a fetch of the files, this will result in the following behavior on the portal:

• The parsed index.md markdown file on the ‘General information’ page of our API

• On the ‘Documentation’ tab of our API we have:

• • a folder called ‘Code samples’ with 2 pages: the ‘Asciidoc page’ and the ‘Markdown page’
  • The ‘Swagger’ page loaded from openapi.yaml

Syntax highlighting in your technical documentation can be done with the standard features supported in the asciidoc or markdown syntax. For more details see: https://www.markdownguide.org/extended-syntax/#syntax-highlighting.