Add and publish API product documentation

The Dev Portal is an API catalog that lets you document and publish your Konnect API products and share them with your developers. Developers can use the Dev Portal to locate, access, consume, and register applications to the products.

This guide walks you through associating API specs and product documentation with your API products, and viewing any published content, and Dev Portal specific customization options.

Published API products become immediately available to users who have access to the Dev Portal. When an API product is published, the API spec and any product documentation becomes discoverable. We use the term discoverable here because the Dev Portal can create a unified API experience where a developer can navigate through the different APIs that are available, read documentation, test endpoints within the Dev Portal, and register to create applications for specific APIs.

Add Product Documentation

You can provide extended descriptions of your Konnect API products with a Markdown (.md) file. The contents of this file will be displayed as the introduction to your API in the Dev Portal.

1. Write a description for your API in Markdown (.md).

   If you don’t have a file you can use for testing, copy the following text into a blank .md file:

    Here's a description with some **formatting**.
   
    Here's a bulleted list:
    * One
    * Two
    * Three
   
    You can [add relative links](/) and [absolute links](https://cloud.konghq.com).
   
    Try adding a codeblock for code snippets:
   
        This is a test
   
   

2. In the API Products, select a service.

3. Select Documentation, upload your documentation, add a Page name, and an optional URL slug.
4. Click Save.

Add an API Spec

Every version can have one OpenAPI spec associated with it, in JSON or YAML format.

If you have a spec, use it in the following steps. Otherwise, you can use the sample Analytics spec for testing.

1. From the API Products dashboard, select Product Version then click the product version you want to upload the spec for.

2. In the API Spec tab, click Upload.

3. Select a spec file to upload.

   The spec must be in YAML or JSON format. To test this functionality, you can use vitalsSpec.yaml as a sample spec.

   Note: Supported version fields are swagger: "2.0" and those that match openapi: x.y.z (for example: openapi: 3.1.0). OpenAPI spec versions 2.0 or later are supported.

This OpenAPI spec will be shown under the version name when this service is published to the Dev Portal.

Publish an API product and API product version to a Dev Portal

To publish an API, you must publish both the API product and API product version to the Dev Portal.

1. In Dev Portal, select the Dev Portal you want to publish the API for.
2. Click API Products.
3. Select the API product you want to publish. On the API product overview page, click Add and select Publish to Dev Portals in the menu.
4. Click Publish to publish your API product to a specific Dev Portal.
5. In API Products, select the API product you added to the Dev Portal.
6. Click Product Versions in the sidebar.
7. Click the product version you created previously and want to publish to your Dev Portals. From the Actions menu or the Dev Portals tab, click Publish to Dev Portals and select the Dev Portals you want to publish the product version to.

The API product and product versions should now display in the Dev Portals you selected.

View the published content on Dev Portal

In this section, you can take one of two paths: keep the Dev Portal private and require a login, or switch it to public, making it visible to anyone with a link.

If you choose to make the Dev Portal public, application registration will not be available.

Note: The Dev Portal is a separate site that requires its own credentials. You can’t use your Konnect credentials to log in here.

Summary

In this topic, you added documentation for your API product and logged into the Dev Portal to check out the API product documentation live.

More information

• API product documentation: This doc explains how to upload, edit, and publish product documentation using the API Products dashboard and publish API product to the Dev Portal to be consumed by your users.
• Manage Konnect API product versions: This explains how to manage the API product version for your services, including the status of the API product version. API product versions can have a status of “Published”, “Deprecated”, or “Unpublished”.
• Register an application to the API product.
• Customize Dev Portal