The metadata.json file

This is a json file which tells the Developer portal where the documentation shall be synced in to on the Developer portal. Below and example on such a file:

It is required to have in the document repository for the automatic sync to work.

{
  "serviceName": "Plattform", # Must exist in umbraco
  "productName": "Utviklerportal",
  "apiName": "API Management Platform",
  "productFolderDisplayName": "Developer portal.",
  "apiFolderDisplayName": "Api documentation",
  "docsFolderDisplayName": "Documentation",
  "utviklerportalBranches": ["main","next-version"],
  "openApiFolderDisplayName": "Swagger documentation",
  "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://app-utviklerportal-utvikling.azurewebsites.net/swagger/v1/swagger.json"
    }
]
}

This is the main components of the metadata.json file

• "serviceName": This is the service ("Tjeneste") on the Developer portal where the files will be placed. mandatory.
• "serviceDescription": This is the description of the service ("Tjeneste").
• "productName": This is under which product under the service. A service can have multiple products. If not set, the product level is skipped.
• "productDescription": This is the description of the product.
• "productFolderDisplayName": This is display name for the product if you want something other than the default.
• "docsFolderDisplayName": This is display name for the docs folder if you want something other than the default ("docs").
• "utviklerportalBranches": You can have more than main branch, ie for documenting future versions. Name it here and it will be synced.
• "apiName": The api catalog created under the service or product. mandatory.
• "ApiDescription": The description of the api.
• "apiFolderDisplayName": This is display name for the api folder if you want something other than the default.
• "openApiFolderDisplayName": This is display name for the product if you want something other than the default.
• "openApis": The Developer portal can render a swagger UI. The requirement is that there exists a swagger endpoint open on the internet that is reachable from the Developer portal.
  • "name": The name of the item. mandatory if you have openApis
  • "url": The swagger endpoint. mandatory if you have openApis
  • "servers": Will populate the "Servers" dropdown. Must be used if "Try it out" should be used, ie to redirect the call when doing a "Try it out".

Here's an example showing the display names.

Note there can be several document repositories that refer to the same serviceName. This is useful if you have several teams working on the same service. Then the documentation will be placed under the same service. As an example, if to document repos, where both metadata.json point to the same serviceName, both will be placed under same serviceName.

In the same way, there can be several document repositories that refer to the same serviceName and productName. Then the documentation will be placed under same serviceName and productName.

The first time the metadata.json file is committed into the repo, the catalog (pre developer portal) needs to be updated. The update of new products will only be done once per hour. So worst case you will need to wait one hour before you can see your new product on the Developer portal. After this has been done, the files will be updated almost immediately.