Teknisk beskrivning av tjänsten i API-katalogen
Varje tjänst ska ha en allmän beskrivning samt en teknisk beskrivning som kan läsas automatisk till API-katalogen från Informationsleden. Dessa tekniska beskrivningar bör vara antingen:
- WSDL-beskrivningar för SOAP-tjänster eller
- OpenAPI 3-beskrivningar vid REST-tjänster
Du måste lägga till beskrivningen för din tjänst i anslutningsserverns administration användargränssnitt och sedan visas den automatiskt i API-katalogen.
Dokumentera tjänster som följer REST-arkitekturen i enlighet med OpenAPI-specifikationen. API-katalogen har en förhandsvisning av OpenAPI-beskrivningarna, varvid den som bläddrar i katalogen snabbt får de viktigaste uppgifterna om din tjänst. Om du inkluderar länkar i beskrivningen ska du se till att de fungerar och inte är till exempel interna länkar. Läs mer om OpenAPI-dokumentation::
- OpenAPI specification (GitHub, på engelska)Öppnas i ett nytt fönster.
- OpenAPI basic structure (på engelska)Öppnas i ett nytt fönster.
Observera att beskrivningen måste vara i enlighet med OpenAPI 3.0 versionen för att förhandsvisningen ska visas automatisk i API-katalogen. Om du använder till exempel OpenAPI 2.0 versionen, måste du lägga till beskrivningen manuellt till API-katalogen.
Tjänster som saknar den tekniska beskrivningen (antingen WSDL eller OpenAPI 3) visas som okända tjänster i API-katalogen.
Okänd tjänst i API-katalogen
Din tjänst visas som okänd i API-katalogen om den saknar gränssnittsbeskrivning i anslutningsserverns administration användargränssnitt på Informationsleden. Utan gränssnittsbeskrivning kan API-katalogen inte identifiera om din tjänst har formatet REST eller SOAP.
En okänd tjänst är oftast en REST-tjänst som lagts till i Informationsled i formatet REST API base path. API-katalogen identifierar inte REST-tjänster som lagts till med REST API Base Path. Gränssnittsbeskrivningen ska ha formatet OpenAPI 3 för att API-katalogen ska kunna visa den. Vi rekommenderar att du lägger till REST-tjänster med stigen OpenAPI 3 Description i Informationsleden för att API-katalogen ska kunna identifiera tjänsten och automatiskt visa gränssnittsbeskrivningen.
I vissa fall kan SOAP-tjänsten förlora WSDL-beskrivningen och då syns även den som en okänd tjänst.
Så här lägger du till en beskrivning
Sättet att lägga till en beskrivning beror på om din tjänst är en REST- eller SOAP-tjänst.
1. För en REST-tjänst som lagts till i Informationsledet med REST API Base Path
Om du inte kan publicera gränssnittsbeskrivningen i formatet OpenAPI 3 ska du lägga till tjänstens gränssnittsbeskrivning i API-katalogen som en bilaga till subsystemet. Gränssnittsbeskrivningen kan t.ex. vara en Open API 2-beskrivning i JSON-format. Du kan se exempel på Skogscentralens beskrivningar i subsystemetÖppnas i ett nytt fönster..
- Lägg till bilagorna på subsystemets sida genom att välja Hantera > Bilagor > Lägg till ny resurs.
- Fyll i fälten. Namnge bilagorna tydligt så att de som utnyttjar tjänsten vet vilken tjänst gränssnittsbeskrivningen hör till.
- Välj till sist Lägg till.
Lägg även till en kort allmän beskrivning av tjänsten på dess egna sida och nämna att det finns en separat bilaga med gränssnittsbeskrivningen. Lägg till en beskrivning från tjänstens sida genom att välja Hantera. Då syns din tjänst ännu som okänd, men användare som vill utnyttja din tjänst förstår tjänstens funktion bättre med hjälp av gränssnittsbeskrivningen.
Du kan senare ändra de tjänster som lagts till med REST API Base Path till formatet OpenAPI 3 Description. Då ska du först separat lägga till OpenAPI 3 beskrivningsstigen och testa att den fungerar innan du raderar den ursprungliga REST API Base Path-stigen.
2. För SOAP-tjänster
SOAP-tjänster ska ha en WSDL-beskrivning i anslutningsserverns administration användargränssnitt för att API-katalogen ska kunna visa gränssnittsbeskrivningen.
Om din SOAP-tjänst syns som okänd i API-katalogen ska du kolla i anslutningsserverns administrations användargränssnitt om WSDL-beskrivningen har försvunnit. Om beskrivningen har försvunnit ska du lägga till WSDL-beskrivningen på nytt. Beskrivningen adderas automatiskt även till API-katalogen.
Läs mer i Suomi.fi-serviceadministrationens anvisningar om hur du lägger till en WSDL-beskrivning på anslutningsservern. Se även hurdan WSDL-beskrivningen ska vara. Din tjänst borde synas normalt i API-katalogen redan nästa dag.
Kontakta Informationsledens support på palveluvayla@palveluvayla.fi Öppnas i ett nytt fönster.om dessa anvisningar inte var till hjälp i din situation.