Using OpenAPI

The Developer Portal supports the use of OpenAPI / Swagger docs. You will be able to add as many Swagger documentation pages as needed using the metadata.json scheme.

Adding OpenAPI definitions to your metadata.json

Using the metadata.json scheme, you can add Swagger documentation pages by following the example below:

{
    "serviceName": "",
    "serviceDescription": "",
    "productName": "",
    "apiName": "",
    "productFolderDisplayName": "",
    "apiFolderDisplayName": "",
    "docsFolderDisplayName": "",
    "openApiFolderDisplayName": "",
    "utviklerportalBranches": ["", ""],
    "syncWithPortal":true,
    "openApis": [
        {
            "name": "Katalogen",
            "url": "https://catalog-p.plattform.nhn.no/swagger/v1/swagger.json",
            "servers": ["https://catalog-dev.plattform.nhn.no"]
        },
        {
            "name": "Utviklerportalen Interne API",
            "url": "https://utviklerportal.nhn.no/swagger/default/swagger.json"
        }
    ]
}

The schema for each openApi object looks like this:

"openApis": [
    {
        "name": string,
        "url": string,
        "servers": string[]
    },
    {
        "name": string,
        "url": string,
        "servers": string[]
    }
]

Note that the url provided must lead to a valid and reachable swagger.json document in order for the Swagger UI script to render properly.

Using the Test Token Tool (TTT)

The Developer Portal's OpenAPI / Swagger implementation supports the use of the Test Token Tool in order to generate tokens for try-it-out functions.

In order to enable and use the TTT, you must access your OpenAPI content node in the Portal Backoffice. Here you can provide a valid scope (one or more string values) and audience (string).

When both scope and audience are provided the TTT will automatically be enabled when the Swagger document is rendered.

Enabling DPoP for Swagger documents

The Developer Portal's OpenAPI / Swagger implementation also supports DPoP.

Just like with the TTT, DPoP can be enabled by accessing the OpenAPI content node in the Portal's Backoffice.

Here you'll find a simple toggle that turns DPoP on and off for the specific content node. Note that in order for DPoP to function correctly, you will need to include all relevant definitions in your swagger.json file.

If the toggle is set and the relevant definitions are present, DPoP should automatically switch on for your Swagger document.

Setting Security Level

You can set a numeric value for the security level on the OpenAPI content node in the Backoffice.

This security level is used in regards to Swagger/OpenAPI documents that uses Helse ID / DPoP / Test Token Tool.

Where to set it:

Open the OpenAPI content node in the Backoffice and enter a numeric value in the Security level field.

You can read more on the security level at HelseID's documentation.

Setting HPR number, person identifier, and person name

You can also provide optional user-claim values on the OpenAPI content node in Backoffice:

• HPR number (hprNumber)
• Person identifier (personIdentifier, mapped to pid)
• Person name (personName, mapped to name)

These values are used by the Test Token Tool flow for Swagger/OpenAPI documents using HelseID.

Where to set them:

Open the OpenAPI content node in Backoffice and fill in the relevant fields.

When set, the values are forwarded as user claims in token requests:

• userClaimsParameters.hprNumber
• userClaimsParameters.pid
• userClaimsParameters.name