Chapter 3. Adding ActiveDocs to 3scale


3scale offers a framework to create interactive documentation for your API.

With OpenAPI Specification (OAS), you have functional documentation for your API, which will help your developers explore, test, and integrate with your API.

3.1. Setting up ActiveDocs in 3scale

You can add ActiveDocs to your API in the 3scale user interface to obtain a framework for creating interactive documentation for your API.

Prerequisites

  • An OpenAPI document that defines your API.
  • A 3scale 2.14 instance tenant’s credentials (token or provider_key).

Procedure

  1. Navigate to [your_API_name] ActiveDocs in your Admin Portal. 3scale displays the list of your service specifications for your API. This is initially empty.

    You can add as many service specifications as you want. Typically, each service specification corresponds to one of your APIs. For example, 3scale has specifications for each 3scale API, such as Service Management, Account Management, Analytics, and Billing.

  2. Click Create a new spec.

    When you add a new service specification, provide the following:

    • Name
    • System name

      This is required to reference the service specification from the Developer Portal.

    • Choose whether you want the specification to be published or not. If you do not publish, the new specification will not be available in the Developer Portal.

      Note

      If you create, but do not publish your new specification, it will remain available to you for publication at a later time of your choosing.

    • Add a description that is meant for only your consumption.
    • Add the API JSON specification.

      Generate the specification of your API according to the specification proposed by OpenAPI Specification (OAS). In this tutorial we assume that you already have a valid OAS-compliant specification of your API.

Working with your first ActiveDoc

After you add your first ActiveDoc, you can see it listed in [your_API_name] ActiveDocs. You can edit it as necessary, delete it, or switch it from public to private. You can detach it from your API or attach it to any other API. You can see all your ActiveDocs, whether or not they are attached to an API in Audience Developer Portal ActiveDocs.

You can preview what your ActiveDocs looks like by clicking the name you gave the service specification, for example, Pet Store. You can do this even if the specification is not published yet.

This is what an ActiveDoc looks like:

ActiveDocs new specification view
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.