How to use OpenAPI files with GitSync

This guide explains how to use OpenAPI spec files with GitSync

Steps (Assuming you write your documentation in GitHub/GitLab):

  1. Configure a space with GitSync.

  2. In the root of your GitHub repository, or in the directory you configured in GitSync, upload your OpenAPI spec file. For the purposes of this guide, we are using a file called sample.yaml

  3. Create a page in your repository, say Page.md, where you want your OpenAPI documentation to be displayed

  4. In the Page.md file, create blocks like the following. Here, sample.yaml is the name of your OpenAPI spec file, the value of path is the endpoint you want to create the block out of, and the value of method is the method you want to create the block out of. Commit your changes.

{% swagger src="sample.yaml" path="/stars" method="post" %} sample.yaml {% endswagger %}

  1. After the sync with GitBook succeeds, you will see a block that looks like the following in GitBook

  1. You can create such swagger blocks in your file for every path and method you want to document in GitBook.

Steps (Assuming you write your documentation in GitBook):

  1. In the Space and in the page you want to add your OpenAPI operations, open up the command mode in GitBook by pressing forward slash ('/') from within the GitBook app.

  2. Search for OpenAPI in the search window and select OpenAPI.

  1. Select the file you want to upload, and select all the API operations you want to import, and click on Insert Blocks.

  1. The chosen API operations will be imported in GitBook, and if you have GitSync enabled on the space, swagger blocks will be exported to GitHub/GitLab, representing the operations you have imported.

Last updated