Heretto API Docs

API Docs Overview

Learn how to use Heretto API Docs to publish API documentation for public and internal consumption within Heretto Portal, ultimately achieving a more streamlined and unified approach to full service documentation.

With API Docs, you can publish JSON files with API specifications to your Heretto Portal environment. API Docs includes built-in API testing which enables you to access and test your API documentation alongside your other content.

You store your JSON files with API endpoint definitions in Heretto CCMS which enables you to manage both product and API documentation centrally. Next to API endpoint definitions generated from JSON files, your API documentation can contain traditionally created content. For example, an API overview, information about API calls flow, security, and more.

To publish API specifications, you upload your JSON file(s) with API endpoint definitions to the CCMS, attach them to a map, and publish it to Heretto Portal. Upon publishing to the portal, JSON files are converted into help portal pages in Heretto Portal.

API documentation published to Heretto Portal enables users to:

Reference general information about the API
Reference API endpoint attributes and properties
Test parameter values by making API calls to a specified server
Generate a usable request sample rendered in commonly used programming languages with values provided through the pages

Tip:

To see API Docs in action, see our Heretto Deploy API documentation at Deploy API Introduction.

API Docs Facts and Recommendations

JSON File

Heretto API Docs are compatible with OpenAPI. The JSON file(s) with API endpoint definitions must conform to OpenAPI Specification. The earliest supported version is version 2.0 (former Swagger RESTful API Documentation Specification). We recommend using versions 3.0.1 - 3.0.3.
To send API calls to your servers or create usable request samples in Heretto Portal, each JSON file must have at least one server configured. JSON files can have multiple servers configured, and server URLs can differ between files. Endpoints only use servers from the JSON file in which they are added. If a JSON file does not have servers configured, you will not be able to send requests using endpoints defined in this file.
Ensure each endpoint has a summary parameter value specified. Values provided in that field are used as the navigation menu label and page title for each endpoint. Here is an example of a summary value in a JSON file and how it is presented in the portal.
```
"paths": {
    "/org/{organizationId}/deployments/{deploymentId}/search": {
      "post": {
        "tags": [
          "API Endpoint Specification"
        ],
        "summary": "Search pages",
```
Figure 1. The Search pages summary in Heretto Portal

Structure of content generated from JSON file(s)

Each unique value present in tags objects in the JSON file becomes a separate heading in the table of contents in Heretto Portal.
Endpoints with identical tags values are grouped under one heading.
Headings generated from tags appear in the same order as in the JSON file.
To specify the value displayed in the TOC for each API method, ensure there is a summary parameter noted. If you do not include a summary parameter, the TOC shows the API method path instead.
The tags objects can contain values that differ only by letter case. If that is the case, the second instance of the value gets appended with _1, the third instance with _2, and so on. This suffix is visible in the portal output.
Known limitations that apply within a single .json file:
- One tags object can't contain operationId objects with the same values
- If two tags objects differ only by the letter case, they can't contain operationId objects with the same values

Map types

You can add JSON file(s) to maps, bookmaps, sitemaps, and custom (or specialized) maps.

Map structure

A map can contain one or more JSON file(s).
You add JSON file(s) to a map in a topicref element. In the Content Editor, you can drag and drop JSON file(s) from the Content Library onto a map to add it to the map.
To render API Docs properly in Heretto Portal, apart from a JSON file, a map or a sitesection must contain at least one DITA topic. There should be at least one topicref in each sitesection.

Chunk attribute

API Docs does not support adding the chunk attribute on a topicref element that points to a JSON file.
API Docs does not support adding JSON file(s) inside a structure that uses chunk="to-content".

API Docs Map Structure Examples

Review examples of map structures valid for publishing your API specification with Heretto API Docs. A correct map structure and attributes are required to properly render content in JSON file(s) with API endpoint definitions.

A minimal map structure with one DITA and one JSON file.

<map id="ditamap-1111">
   <topicref href="api-overview.dita"/>
   <topicref format="json" href="api-reference.json" outputclass="openapi-reference"/>
</map>

A map structure with JSON files nested under DITA topics.

<map id="ditamap-2222">
    <topicref href="api-overview.dita"/>
        <topicref href="api-module-1.dita"/>
            <topicref format="json" href="api-reference-1.json" outputclass="openapi-reference"/>
        </topicref>
        <topicref href="api-module-2.dita"/>
            <topicref format="json" href="api-reference-2.json" outputclass="openapi-reference"/>
        </topicref>
</map>

A sitemap structure with a few DITA topics and one JSON file.

<sitemap id="ditamap-3333"> 
    <title>API Documentation</title>
        <topicref href="api-overview.dita"/>
        <topicref href="authentication.dita" chunk="to-content">
            <topicref href="oauth.dita"/>
        </topicref>
        <topicref href="security.dita"/>
        <topicref href="tokens.dita" chunk="to-content">
            <topicref href="create-a-simple-token.dita"/>
            <topicref href="create-a-jwt-token.dita"/>
        </topicref>
        <topicref href="api_reference.json" outputclass="openapi-reference"/>
</sitemap>

A sitemap structure with sitesections two DITA topics and three JSON files.

<sitemap id="ditamap-4444"> 
    <title>API Documentation</title>
    <sitesection>
        <topicmeta>
            <navtitle>Usage Data</navtitle>
        </topicmeta>
        <topichead>
            <topicref href="extract--usage-data-from-database.dita"/>
            <topicref href="api_reference-1.json" outputclass="openapi-reference"/>
        </topichead>
    </sitesection>
    <sitesection>
        <topicmeta>
            <navtitle>User Management</navtitle>
        </topicmeta>
        <topichead>
            <topicref href="api-user-management.dita"/>
            <topicref href="api_reference-2.json" outputclass="openapi-reference"/>
            <topicref href="api_reference-3.json" outputclass="openapi-reference"/>
        </topichead>
    </sitesection>        
</sitemap>

Create a Map for API Documentation

Heretto API Docs enables you to use JSON files with API endpoint definitions to automatically create API endpoint documentation.

Make sure:

You have a valid JSON file conforming to OpenAPI Specification 3.0.1 - 3.0.3
Your map contains at least one topicref pointing to a DITA topic

Upload JSON file(s) containing endpoint definitions to Heretto CCMS.
In Heretto CCMS, open the map to which you want to add your API endpoint specification.

For examples of valid map structures, see API Docs Map Structure Examples.
In the map, click Open Library and navigate to the JSON file(s) you uploaded.
Drag and drop the JSON file(s) on your map. Make sure the element type for each file is <topicref>.
For each <topicref> with a JSON file:
1. In the map tree pane, hover over a topicref with a JSON file and click Edit element properties .
2. In the outputclass field, enter openapi-reference.
A valid topicref with a JSON file.
```
<topicref href="api_reference.json" outputclass="openapi-reference"/>
```
Publish the map to your help site to make your API documentation available to your audience.

The API endpoint documentation is published to your help site.

Edit Endpoint Headings in the JSON File

To create a structure for your API documentation, Heretto API Docs uses values present in the tags objects in the JSON file(s) you attached to the map. To modify this structure, edit the JSON file(s). Each unique value of tags creates a separate heading in the table of contents in Heretto Portal. Endpoints with identical tags values are grouped under one heading.

In the Content Library, right-click the JSON file you want to edit and click Edit Source.
In the Source Editor, locate a tags object and change its value.
The tags object value is now API Endpoint Specification.
```
"paths": {
    "/org/{organizationId}/deployments/{deploymentId}/search": {
      "post": {
        "tags": [
          "API Endpoint Specification"
        ],
```
This value will appear as a heading in the table of contents in Heretto Portal.
Repeat 2 for each endpoint in the JSON file.
Tip:
Depending on the number and the logical structure of endpoints in your JSON file, you may want to:
- Group them under one heading: make sure that all tags objects have the same value for all endpoints.
- Separate them into multiple groups: use different tags values for each group of endpoints.
Save your changes.
Publish changes to your help site.

Testing API Calls in Heretto Portal

Heretto API Docs enables you to test API endpoints directly in Heretto Portal where you can set request parameters and send requests to servers previously defined in the JSON file(s) that contains your API endpoint specification. The request you send also appears as a request sample in a programming language of your choice. You can use request samples directly in your code.

Figure 2. API Test Area Overview.

Security schemes menu
Request parameters
Server menu (appears if two or more servers are configured in a JSON file containing the API specification)
Programming language menu
Copy code button

Configure API Docs with Your Servers

To test API calls on your help portal, each JSON file that contains your API must have at least one address to a server that receives requests.

You can define multiple servers in one JSON file. The servers can be the same for all files, or differ between files. If a JSON file does not contain any servers, it is not possible to send requests with endpoints from this JSON file.

In the Content Library, right-click the JSON file you want to edit and click Edit Source.
In the Source Editor, locate the servers object and inside it, add a url object for each server.
To each url object assign a value that is the URL to your server.
The url object values are: https://server1.example.com/ and https://server2.example.com/.
```
"servers": [
    {
      "url": "https://server1.example.com/"
    },
    {
      "url": "https://server2.example.com/"
    }
  ],
```
Save your changes.
Publish the changes to your help site.

The server address appears in the request URL below the page title and in the request sample.

If a JSON file contains two or more servers, the server menu appears in the API test area of your help site. The server menu enables you to switch between servers.

Send API Requests

You can test API requests directly in Heretto Portal. You can then copy the request snippet in your chosen programming language and use it directly in your code.

Your JSON file with API endpoint specification must have defined one or more servers
You must have API endpoint documentation published to your help site
If your servers are secured, you must have valid credentials for making requests to your servers

On your help site, navigate to the page with the description of your chosen endpoint.
In the API test area, click the security scheme list and choose an authentication method.
In the Auth section, paste an authentication string according to the chosen method.
In the Parameters section, enter values for your request.
Note:
- The parameters marked with an asterisk (*) are mandatory.
- All values you enter also appear in the Request Sample area.
Optional: To change the server, click the Server menu and select a different server from the list.
Click Send API Request.

A server response appears below the API test area.

Configure a CORS Proxy for API Docs

You can configure Heretto Portal to act as a cross-origin resource sharing (CORS) proxy for API Docs. A CORS proxy is a service that enables you to access resources from other websites without having to own that website.

In the Content Library, right-click your portal config.json file and select Edit Source.
In the Source Editor, add this code:
```
"apiDocsConfig": {
    "tryItCorsProxy": "true"
},
```
Tip:
Make sure to use a trailing comma after the closing curly brace if needed, or remove it if you add this to the very end of your JSON file.
Save your changes.
Publish the changes to your help site.

Customize API Docs Styling

You can customize the layout of Heretto API Docs, similarly to the Heretto Portal.

API Docs use the same CSS file as Heretto Portal. For more information on styling, see: Customize Heretto Portal Styling.

Gretyl's Portal

Heretto Help