Muhammad Saeed September 28, 2023

redocly-cover-smaller

Redocly is a popular developer documentation platform with support for a developer portal and API docs with a developer-friendly workflow for creating and maintaining documentation. In this article, we’ll focus on how to extend Redocly’s API Docs tool by incorporating SDKs generated by APIMatic.

At APIMatic, we generate strongly typed SDKs along with language-specific documentation and code samples, all built from OpenAPI definitions.

In this post, we’ll look at how APIMatic-generated SDKs can be embedded into Redocly’s API Reference solution to elevate the API Integration experience for your developers. This screenshot shows what we are going to build in this tutorial:

APIMatic SDKs integrated inside Redoc API docs for Swagger Petstore API

This article assumes you have already signed up to Redocly, set up your GitHub repository, connected it to Redocly’s API registry and added your API definition to the registry. If not then follow the Redocly API registry quickstart guide.

Generate SDKs and documentation

It’s easy to get started with APIMatic, just follow the steps below. If you already have a generated portal with APIMatic, skip to the next section.

  1. Sign up for your APIMatic account.
  2. Follow these steps to Import your API definition.
  3. Once imported, click the Generate button and then click Proceed.
  4. This will open a window. Click on the Preview API Portal.
  5. You will be redirected to a new window to preview your generated SDK documentation.APIMatic DX Portal for Swagger Petstore API

Publish your SDK documentation

Next, publish your SDK documentation so it is publicly accessible. Click the Customize button on the banner that appears at the bottom of your screen.

  1. Click on the Publish Portal button on the top right of the Portal Editor.
  2. You will be prompted to select a hosted or embedded portal. Select the Hosted option.
  3. Select the API version for which you want to publish this documentation and click Next.
  4. You need to provide a slug where this documentation will be hosted. The slug can contain one or more words separated by a dash “–“. Provide a unique slug in the textbox and click the Save & Next button.
  5. With your unique URL set up, click the Publish button to initiate the publishing process. You’ll receive an email notification as soon as the process is complete.
  6. Once publishing is complete, visit your unique URL to view your SDK documentation. You can also find the URL in the portal Settings > Publishing section of the portal editor.

APIMatic DX portal publishing page

SDKs in your Redocly API Docs

Let’s insert APIMatic SDKs into your Redocly API docs.

Redocly API docs render the main description of an API definition as a separate section. We will leverage this capability to create an SDK section at the beginning of our API Docs.

Open your Redocly Source Directory and navigate to your OpenAPI Description file. If you used the sample GitHub Repository provided by Redocly, this should be the openapi/openapi.yaml file.Open API spec file path in a Redoc API Registry

Find the info -> description property and determine if the value is provided inline or contains a $ref link to a separate markdown file. In the case of the latter, you can skip down to use our API description template.
 
Create a new markdown page in your repository named api-description.md inside the openapi/ directory.
Redoc API Registry file structure

Copy the info -> description value from the OpenAPI spec file and paste it into the newly created api-description.md file to retain the original description.

Now update the info -> description property in the OpenAPI spec by adding a $ref property to it with the correct path to the api-description.md file as shown in the screenshot below.Using $ref property to set description in an Open API 3.0 spec file

API Description Template

We’ve created a markdown template to help you add your APIMatic SDKs to your Redocly API Docs. Copy the contents of the template from here and paste them inside the api-description.md file after your original description text.

Customize API Description Markdown

You will now need to replace the YOUR DOCS SLUG and YOUR API KEY placeholders with the actual values for your SDK documentation.
Detailed instructions for doing this are listed below:
  1. YOUR DOCS SLUG represents a part of the URL where your APIMatic Portal is published. To retrieve this value, hover over the top left corner of your API definition tile in the APIMatic Dashboard and copy the link that appears. You will just need the last section of this URL e.g. https://www.apimatic.io/apidocs/YOUR DOCS SLUG. Replace all instances of YOUR DOCS SLUG in the api-description.md file with this value. Swagger Petstore API imported in APIMatic
2. YOUR API KEY represents a unique identifier for your SDK documentation. In order to access the API Key for your SDK documentation, click the kebab menu (three vertical dots) on the API definition tile to retrieve the API integration key.

Swagger Petstore API imported in APIMatic

3. From the context menu, select API Integration Keys.
4. Copy the property titled API KEY. In the api-description.md file, replace all instances of YOUR API KEY with this value.

This concludes the steps required to add an SDK section to your API Documentation. Commit your changes and push them to GitHub. 

Redocly will automatically build the API docs based on your changes. Once the build process is complete, you can view the API docs and see the published changes. 

APIMatic SDKs integrated inside Redoc API docs for Swagger Petstore API

🎉 Congratulations, you have successfully embedded APIMatic SDKs inside your Redocly API Docs.

Conclusion

The foundation of a good API program is documentation. As your developer audience expands, the need for an SDK program becomes a priority. It’s great to have flexibility when choosing from an array of tools to build your overall developer experience.

APIMatic provides an extensible code generation solution that works with virtually every documentation solution on the market. If you’ve liked what you read, sign up for a free 14-day trial of APIMatic and get started! 

We would love to see what you build. Tweet your updated Redocly docs to us at @APIMatic or drop a mention on Linkedin.