The metadata.json fil

Dette er en json‑fil som forteller Utviklerportalen hvor dokumentasjonen skal synkroniseres til på portalen. Nedenfor er et eksempel på en slik fil:

Det er påkrevd å ha den i dokumentasjons‑repoet for at den automatiske synkroniseringen skal fungere.

{
  "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"
    }
]
}

Hovedkomponentene i metadata.json‑filen

• "serviceName": Navnet på tjenesten i Utviklerportalen der filene skal plasseres. Obligatorisk.
• "serviceDescription": Beskrivelsen av tjenesten.
• "productName": Hvilket produkt under tjenesten filene hører til. En tjeneste kan ha flere produkter. Hvis dette ikke settes, hoppes produktnivået over.
• "productDescription": Beskrivelsen av produktet.
• "productFolderDisplayName": Visningsnavn for produktmappen dersom du vil ha noe annet enn standardnavnet.
• "docsFolderDisplayName": Visningsnavn for docs‑mappen dersom du vil ha noe annet enn standard ("docs").
• "utviklerportalBranches": Du kan ha flere enn kun main‑grenen, f.eks. for å dokumentere fremtidige versjoner. Navngi dem her, så blir de synkronisert.
• "apiName": Navnet på API‑katalogen som opprettes under tjenesten eller produktet. Obligatorisk.
• "apiDescription": Beskrivelsen av API‑et.
• "apiFolderDisplayName": Visningsnavn for API‑mappen dersom du vil ha noe annet enn standard.
• "openApiFolderDisplayName": Visningsnavn for OpenAPI‑mappen dersom du vil ha noe annet enn standard.
• "openApis": Utviklerportalen kan vise en Swagger‑UI. Kravet er at det finnes et offentlige Swagger‑endpoint som er tilgjengelig fra Utviklerportalen.
  • "name": Navnet på elementet. Obligatorisk hvis du har openApis.
  • "url": Swagger‑endpointen. Obligatorisk hvis du har openApis.
  • "servers": Populerer «Servers»-nedtrekksmenyen. Må brukes dersom «Try it out» skal fungere, dvs. for å omdirigere kallet når du prøver det i UI‑en.

Her er et eksempel som viser hvordan visningsnavn kan settes.

Merk: Det kan finnes flere dokumentasjons‑repoer som peker på samme serviceName. Dette er praktisk dersom flere team jobber med samme tjeneste – dokumentasjonen vil da samlet plasseres under den samme tjenesten.
Eksempel: To repoer med metadata.json som begge har samme serviceName vil bli lagt inn under samme tjeneste.

På samme måte kan flere repoer også peke på samme kombinasjon av serviceName og productName. Dokumentasjonen fra disse repoene vil da bli samlet under både samme tjeneste og samme produkt.

Når metadata.json‑filen blir commitet for første gang, må katalogen (før Utviklerportalen) oppdateres. Oppdateringen av nye produkter skjer kun én gang i timen, så i verste fall må du vente en time før du ser ditt nye produkt i Utviklerportalen. Etter denne oppdateringen vil filene bli synkronisert nesten umiddelbart.