Hur dokumenterar man ett API med OpenAPI?

Hej där! Jag är en API-leverantör (Active Pharmaceutical Ingredient) och idag vill jag prata om hur man dokumenterar ett API med OpenAPI. Det är superviktigt i vårt arbete, eftersom tydlig dokumentation kan göra eller bryta framgången för våra API:er.

Först och främst, låt oss förstå vad OpenAPI är. OpenAPI är en öppen standardspecifikation för att beskriva RESTful API:er. Det ger ett sätt att definiera endpoints, operationer, in- och utdata samt säkerhetskrav för ett API i ett maskinläsbart format. Detta innebär att andra utvecklare enkelt kan förstå och integrera våra API:er i sina applikationer.

Varför det är viktigt att dokumentera API:er med OpenAPI

Som API-leverantör har vi ett gäng bra produkter somMemantinhydroklorid丨CAS 41100 - 52 - 1,Desoximetason丨CAS 382-67-2, ochGlutation丨CAS 70-18-8. För att göra det enklare för våra kunder att komma åt och använda dessa API:er är korrekt dokumentation ett måste.

När vi dokumenterar våra API:er med OpenAPI hjälper det på flera sätt. För det första tillåter det oss att kommunicera tydligt med våra kunder om vad våra API:er kan göra. De kan se exakt vilka slutpunkter som är tillgängliga, vilka parametrar de behöver för att klara och vilken typ av svar de kan förvänta sig. Detta minskar antalet frågor och missförstånd, vilket i sin tur sparar tid för både oss och våra kunder.

En annan fördel är att det främjar interoperabilitet. Eftersom OpenAPI är en öppen standard stödjer många verktyg och ramverk den. Detta innebär att utvecklare kan använda en mängd olika verktyg för att generera klientkod, testa våra API:er och till och med visualisera API-strukturen. Det gör det lättare för dem att integrera våra API:er i sina befintliga system.

Komma igång med OpenAPI-dokumentation

Det första steget i att dokumentera ett API med OpenAPI är att definiera den grundläggande informationen om API:et. Detta inkluderar API:s titel, beskrivning, version och kontaktinformation. Du kan tänka på detta som API:ets "metadata". Du kan till exempel säga något som:

openapi: 3.0.0 info: title: Vårt API för farmaceutiska ingredienser beskrivning: Detta API ger tillgång till information om våra olika aktiva farmaceutiska ingredienser. version: 1.0.0 kontakt: namn: API Support e-post: support@example.com

Därefter måste du definiera servrarna där API:et är värd. Detta talar om för utvecklarna var de faktiskt kan göra förfrågningar till API:t. Du kan ha flera servrar definierade, till exempel en produktionsserver och en testserver.

servrar: - url: https://api.example.com/v1 description: Production server - url: https://test-api.example.com/v1 description: Testing server

Definiera API-sökvägar och operationer

Hjärtat i ett OpenAPI-dokument är definitionen av API-sökvägar och -operationer. En sökväg representerar en specifik slutpunkt i API:t och en operation är en åtgärd som kan utföras på den slutpunkten, som GET, POST, PUT eller DELETE.

Låt oss säga att vi har ett API som ger information om våra läkemedelsingredienser. Vi kanske har en väg som/ingredienserför att få en lista över alla tillgängliga ingredienser.

sökvägar: /ingredienser: få: sammanfattning: Få en lista över alla farmaceutiska ingredienser beskrivning: Returnerar en lista över alla aktiva farmaceutiska ingredienser vi erbjuder. svar: '200': beskrivning: En lista med ingredienser innehåll: application/json: schema: typ: array-objekt: typ: objektegenskaper: namn: typ: sträng cas_number: typ: sträng

I det här exemplet har vi definierat en GET-operation på/ingredienserväg. Sammanfattningen och beskrivningen ger mer information om vad verksamheten gör. Svarsavsnittet definierar vad API:et kommer att returnera när operationen är framgångsrik (statuskod 200). I det här fallet returnerar den en JSON-array av objekt, där varje objekt representerar en ingrediens med ett namn och ett CAS-nummer.

Hantera ingångsparametrar

Många API-operationer kräver inmatningsparametrar. Dessa kan vara frågeparametrar (skickade i webbadressen), sökvägsparametrar (del av webbadressen) eller förfrågningsparametrar (skickas i förfrågans brödtext).

Låt oss säga att vi vill få information om en specifik ingrediens genom dess CAS-nummer. Vi kan definiera en sökvägsparameter för detta.

sökvägar: /ingredients/{cas_number}: get: summary: Få information om en specifik ingrediensbeskrivning: Returnerar detaljerad information om en ingrediens baserat på dess CAS-nummer. parametrar: - namn: cas_number i: sökvägsbeskrivning: CAS-numret för ingrediensen som krävs: sant schema: typ: strängsvar: '200': beskrivning: Information om ingrediensens innehåll: application/json: schema: typ: objektegenskaper: namn: typ: sträng cas_nummer: typ: strängbeskrivning: typ: sträng

I det här exemplet har vi definierat en sökvägsparametercas_numberi/ingredients/{cas_number}väg. Denödvändigfältet indikerar att denna parameter måste anges när begäran görs.

Säkerhet och autentisering

Säkerhet är en avgörande aspekt av alla API. OpenAPI låter dig definiera säkerhetskraven för dina API-operationer. Du kan ange saker som API-nycklar, OAuth 2.0 eller grundläggande autentisering.

Till exempel, om vårt API använder API-nycklar för autentisering, kan vi definiera det så här:

komponenter: securitySchemes: api_key: typ: apiKey namn: X - API - Key in: header security: - api_key: []

I det här exemplet har vi definierat ett säkerhetsschema som heterapi_keysom använder en API-nyckel som skickas iX - API - Nyckelrubrik. Desäkerhetavsnittet på den översta nivån i dokumentet indikerar att alla operationer i API:t kräver denna API-nyckel för autentisering.

Validera och testa OpenAPI-dokumentet

När du har skapat ditt OpenAPI-dokument är det viktigt att validera det för att se till att det följer OpenAPI-specifikationen. Det finns många onlineverktyg tillgängliga som kan hjälpa dig med detta. Du kan också använda verktyg för att generera klientkod från OpenAPI-dokumentet och testa API.

Testning är avgörande för att säkerställa att API:t fungerar som förväntat. Du kan använda verktyg som Postman eller cURL för att skicka förfrågningar till API:t och verifiera svaren. Genom att testa API:t med olika ingångsparametrar och scenarier kan du fånga eventuella buggar eller problem tidigt.

Slutsats och uppmaning till handling

Att dokumentera ett API med OpenAPI är ett kraftfullt sätt att göra ditt API mer tillgängligt och användarvänligt. Som API-leverantör hjälper det oss att bättre betjäna våra kunder och främja användningen av våra produkter somMemantinhydroklorid丨CAS 41100 - 52 - 1,Desoximetason丨CAS 382-67-2, ochGlutation丨CAS 70-18-8.

Om du är intresserad av att lära dig mer om våra API:er eller har några frågor om dokumentationen, hör gärna av dig. Vi är alltid glada att diskutera potentiella partnerskap och hjälpa dig att integrera våra API:er i dina projekt. Oavsett om du är en liten nystartad eller ett stort läkemedelsföretag, kan våra API:er ge värdefull information om våra högkvalitativa farmaceutiska ingredienser.

Referenser

• OpenAPI-specifikationsdokumentation
• Swagger.io - Verktyg och resurser för OpenAPI
• Postman dokumentation för API-testning