"Try it out" functionality

This document describes some considerations for the "Try it out" functionality.

What is it?

As a part of the metadata.json file, there is a section where you can define a link to a swagger endpoint. The data will be imported into the Developer portal and data items will be created in umbraco. Below an example of a metadata.json file.

{
  "serviceName": "Plattform",
  "productName": "Utviklerportal",
  "apiName": "API Management Platform",
  "openApis": [
    {
        "name": "Katalogen",
        "url": "https://catalog-p.plattform.nhn.no/swagger/v1/swagger.json",
        "servers": ["https://catalog-p.plattform.nhn.no"]
    },
    {
      "name": "Utviklerportalen Interne API",
      "url": "https://app-utviklerportal-utvikling.azurewebsites.net/swagger/v1/swagger.json"
    }
]
}

The swagger interface will be rendered as a integral part of the Developer portal, and the user can explore the swagger (openApi) interface without leaving the Developer portal. As a part of the swagger interface, you have a "Try it out" section, and there are a couple of things that need to be set in order to make this work.

The "server" attribute in metadata.json file.

First, the "servers" attribute must be set in the "openApis" section. If not set, the call in the "Try it out" will be done from the uri for the Developer portal (typically "https://utviklerportal.nhn.no"), and since your swagger endpoint does not reside there, that will obviously not work. Setting the "server" attribute will populate a dropdown list on the swagger page, and the user is allowed to choose the correct server. This can typically be one server for test and one server for production environment. Often there is only one server (test environment) and that will be chosen as default in the dropdown.

Your app must whitelist Developer portal.

When doing a "Try it out" call, there is a js call going to the server. Due to set CORS policy, the server receiving the call, must allow for the call to come from another server. The following properties must be considered (and set) on the side that is called:

Access-Control-Allow-Origin: 
This specifies the origin (domain) that is allowed to access the resource. You can specify a specific domain or use * to allow all domains.  

Access-Control-Allow-Methods: 
This specifies the HTTP methods (GET, POST, PUT, DELETE, etc.) that are allowed.  

Access-Control-Allow-Headers: 
This specifies the headers that the client can use in the request.  

Access-Control-Allow-Credentials: 
This specifies whether or not the response to the request can be exposed when the credentials flag is true. It must be a boolean value.

Typically you should set Access-Control-Allow-Origin = "https://utviklerportal.nhn.no"

Below an example of code where this is set on the side which is called, where "host" is typically populated from appsetting.json or an environment variable.

logger ??= LoggerFactory.Create(conf => { }).CreateLogger("CorsExtension");

var hosts = config.GetSection("AllowedHosts").Get<string[]>();
if (hosts is { Length: > 0 })
{
    logger.LogInformation("Using these allowed hosts: {hosts}", String.Join(",", hosts));
    services.AddCors(options =>
    {
        options.AddDefaultPolicy(builder =>
            builder.WithOrigins(hosts)
                .AllowAnyHeader()
                .AllowCredentials()
                .AllowAnyMethod());
    });
}

Automatic CORS verification

The Developer Portal automatically verifies the CORS configuration for each configured API server when a Swagger UI page loads. If CORS is not enabled on the API in question then the 'TRY ME' functionality of swagger UI will not work.

Upon opening a page in utviklerportalen where the swagger APi is misconfigured utviklerportalen will display a warning, and also instructions on how to fix it.

What is checked in the verification process

Three CORS response headers are verified:

All three must pass for the CORS check to succeed.

Banner types

There are three possible outcomes for each server URL:

• No banner (success): All CORS headers are correctly configured. Nothing is displayed to the user.
• Yellow warning banner: The server responded, but one or more CORS headers are missing or incorrect. The banner lists exactly which headers are missing and displays the origin that the API owner needs to whitelist (e.g., https://utviklerportal.nhn.no).
• Red error banner: The CORS check could not be completed. This can happen if:
  • The server could not be reached
  • The request timed out (5-second limit)
  • The URL points to a private or internal address

Resolving CORS issues

If a yellow warning banner is displayed, the API owner needs to update their server's CORS configuration to include the missing headers. Refer to the documentation for your particular coding language/framework for setup guidance and code examples.

If a red error banner is displayed, verify that:

• The server URL configured in the servers property is correct and publicly reachable
• The server is running and responding to requests
• The URL does not point to a private or internal network address (e.g., localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x)

Generating tokens via the HelseID test token tool (TTT) - Defining scope and audience

The Developer portal supports request interception for the SwaggerUI try-it-out functionality.

The use of this function is optional and only needed when authenticating requests with HelseID Test.

This function will intercept the request made by swaggerUI, generating tokens via the TTT and modifying the request header accordingly.

An endpoint and auth key for the TTT is already defined for the Developer portal and does not need to be supplied, but some variables will need to be set up on your openApi document before the request can be intercepted and the token can be generated.

In order for the request interceptor function to run and generate a token via the TTT you must define the correct scope and audience in the backoffice of your openApi page.

These field will be editable in the metadata.json file at a later date, for now you need to do this manually via the backoffice. The required fields in order to trigger request interception are as follows:

Audience - string

Scope - string[]

You are also able to hide the "Authorize" button in the backoffice by using the toggle on the openApi page.

In cases where both audience and scope are provided, the request made by the swaggerUI try-it-out function will be intercepted and the request header will be modified to include the token created by the TTT.

The request made by the swaggerUI try-it-out function will ONLY be intercepted in order to generate a token via TTT if audience and scope is defined. Any request made by the function without scope and audience will not be intercepted and modified.