Red Hat SummitChapter 2. Adding specifications to 3scale
By the end of the section, you will have ActiveDocs set up for your API.
3scale offers a framework to create interactive documentation for your API.
With OpenAPI Specification (OAS) 2.0 (based on the OpenAPI Specification (OAS)) you will have a functional documentation for your API, which will help your developers explore, test and integrate with your API.
2.1. Navigate to service specifications in ActiveDocs
Navigate to [your_API_name]
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.2. Create a service specification
When you add a new service spec, you will have to provide:
- Name
- System name (required to reference the Servcie specification from the Developer Portal)
- Whether you want the specification to be public or not
- A description that is only meant for your own consumption
- API JSON spec, which you can see in the figure below.
The API JSON specification is the "secret ingredient" of ActiveDocs.
You must 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 OpenAPI Specification (OAS) 2.0-compliant specification of your API.
2.3. Working with your first ActiveDoc
Once you have added your first ActiveDoc, you can see it listed in [your_API_name]
You can also preview what your ActiveDocs looks like by clicking on the name you gave the service specification (in the example it was called it Pet Store). You can do this even if the specification is not public yet.
This is what your ActiveDoc will look like:
