Kako dokumentirati API koristeći OpenAPI?

Hej tamo! Ja sam dobavljač API-ja (aktivnog farmaceutskog sastojka) i danas želim razgovarati o tome kako dokumentirati API koristeći OpenAPI. To je izuzetno važno u našem poslu, jer jasna dokumentacija može doprinijeti ili pokvariti uspjeh naših API-ja.

Prvo, hajde da razumemo šta je OpenAPI. OpenAPI je otvorena standardna specifikacija za opisivanje RESTful API-ja. Pruža način za definiranje krajnjih tačaka, operacija, ulaznih i izlaznih podataka i sigurnosnih zahtjeva API-ja u formatu koji se može čitati mašinama. To znači da drugi programeri mogu lako razumjeti i integrirati naše API-je u svoje aplikacije.

Zašto je dokumentovanje API-ja sa OpenAPI važno

Kao dobavljač API-ja, imamo gomilu sjajnih proizvoda kao što suMemantin hidrohlorid丨CAS 41100 - 52 - 1,Desoksimetazon 丨CAS 382-67-2, iGlutation丨CAS 70-18-8. Kako bi našim klijentima olakšali pristup i korištenje ovih API-ja, neophodna je odgovarajuća dokumentacija.

Kada dokumentiramo naše API-je pomoću OpenAPI-ja, to pomaže na nekoliko načina. Kao prvo, omogućava nam da jasno komuniciramo sa našim klijentima o tome šta naši API-ji mogu da urade. Oni mogu vidjeti tačno koje su krajnje tačke dostupne, koje parametre trebaju proći i kakve odgovore mogu očekivati. Time se smanjuje broj pitanja i nesporazuma, što zauzvrat štedi vrijeme i nama i našim klijentima.

Još jedna prednost je što promovira interoperabilnost. Pošto je OpenAPI otvoreni standard, mnogi alati i okviri ga podržavaju. To znači da programeri mogu koristiti razne alate za generiranje klijentskog koda, testiranje naših API-ja, pa čak i vizualizaciju API strukture. To im olakšava integraciju naših API-ja u njihove postojeće sisteme.

Početak rada sa OpenAPI dokumentacijom

Prvi korak u dokumentovanju API-ja koristeći OpenAPI je definiranje osnovnih informacija o API-ju. Ovo uključuje naslov API-ja, opis, verziju i kontakt informacije. Ovo možete zamisliti kao "metapodatke" API-ja. Na primjer, možete reći nešto poput:

openapi: 3.0.0 info: naslov: Opis našeg API-ja za farmaceutske sastojke: Ovaj API omogućava pristup informacijama o našim raznim aktivnim farmaceutskim sastojcima. verzija: 1.0.0 kontakt: ime: API podrška email: support@example.com

Zatim morate definirati servere na kojima se API nalazi. Ovo govori programerima gdje zapravo mogu podnijeti zahtjeve API-ju. Možete imati definirano više servera, na primjer, proizvodni server i server za testiranje.

serveri: - url: https://api.example.com/v1 opis: Proizvodni server - url: https://test-api.example.com/v1 opis: Testni server

Definiranje API staza i operacija

Srce OpenAPI dokumenta je definicija API staza i operacija. Putanja predstavlja određenu krajnju točku u API-ju, a operacija je radnja koja se može izvesti na toj krajnjoj točki, kao što je GET, POST, PUT ili DELETE.

Recimo da imamo API koji pruža informacije o našim farmaceutskim sastojcima. Možda imamo put kao/sastojcida dobijete listu svih dostupnih sastojaka.

staze: /sastojci: dobiti: sažetak: Dobiti listu svih farmaceutskih sastojaka opis: Vraća listu svih aktivnih farmaceutskih sastojaka koje nudimo. odgovori: '200': opis: Lista sastojaka sadržaj: aplikacija/json: shema: tip: stavke niza: tip: svojstva objekta: ime: tip: string cas_number: tip: string

U ovom primjeru, definirali smo GET operaciju na/sastojciput. Sažetak i opis pružaju više informacija o tome šta operacija radi. Odjeljak za odgovore definira šta će API vratiti kada operacija bude uspješna (statusni kod 200). U ovom slučaju, vraća JSON niz objekata, gdje svaki objekt predstavlja sastojak s imenom i CAS brojem.

Rukovanje ulaznim parametrima

Mnoge API operacije zahtijevaju ulazne parametre. To mogu biti parametri upita (poslani u URL-u), parametri putanje (dio URL-a) ili parametri tijela zahtjeva (poslani u tijelu zahtjeva).

Recimo da želimo da dobijemo informacije o određenom sastojku po njegovom CAS broju. Za ovo možemo definirati parametar putanje.

staze: /ingredients/{cas_number}: dobiti: sažetak: Dobiti informacije o opisu specifičnog sastojka: Vraća detaljne informacije o sastojku na osnovu njegovog CAS broja. parametri: - ime: cas_number u: opis putanje: CAS broj potrebnog sastojka: istinita shema: tip: niz odgovori: '200': opis: Informacije o sadržaju sastojka: aplikacija/json: shema: tip: svojstva objekta: ime: tip: string cas_number: tip: opis niza: tip: string

U ovom primjeru definirali smo parametar putanjecas_numberu/sastojci/{cas_number}put. Thepotrebnopolje označava da se ovaj parametar mora navesti prilikom postavljanja zahtjeva.

Sigurnost i autentifikacija

Sigurnost je ključni aspekt svakog API-ja. OpenAPI vam omogućava da definirate sigurnosne zahtjeve za vaše API operacije. Možete odrediti stvari kao što su API ključevi, OAuth 2.0 ili osnovna autentifikacija.

Na primjer, ako naš API koristi API ključeve za autentifikaciju, možemo ga definirati ovako:

komponente: securitySchemes: api_key: tip: apiKey ime: X - API - Ključ: sigurnost zaglavlja: - api_key: []

U ovom primjeru definirali smo sigurnosnu shemu pod nazivomapi_keykoji koristi API ključ poslan uX - API - ključheader. Thesigurnostodjeljak na gornjem nivou dokumenta označava da sve operacije u API-ju zahtijevaju ovaj API ključ za autentifikaciju.

Provjera valjanosti i testiranje OpenAPI dokumenta

Nakon što kreirate svoj OpenAPI dokument, važno je da ga potvrdite kako biste bili sigurni da slijedi OpenAPI specifikaciju. Postoji mnogo dostupnih online alata koji vam mogu pomoći u tome. Također možete koristiti alate za generiranje klijentskog koda iz OpenAPI dokumenta i testiranje API-ja.

Testiranje je ključno kako bi se osiguralo da se API ponaša kako se očekuje. Možete koristiti alate poput Postman ili cURL za slanje zahtjeva API-ju i provjeru odgovora. Testiranjem API-ja s različitim ulaznim parametrima i scenarijima, možete rano uočiti sve greške ili probleme.

Zaključak i poziv na akciju

Dokumentovanje API-ja koristeći OpenAPI je moćan način da vaš API učinite pristupačnijim i prilagođenijim korisnicima. Kao dobavljač API-ja, pomaže nam da bolje služimo našim klijentima i promoviramo korištenje naših proizvoda kao što suMemantin hidrohlorid丨CAS 41100 - 52 - 1,Desoksimetazon 丨CAS 382-67-2, iGlutation丨CAS 70-18-8.

Ako ste zainteresirani da saznate više o našim API-jima ili imate bilo kakva pitanja o dokumentaciji, slobodno nam se obratite. Uvijek nam je drago razgovarati o potencijalnim partnerstvima i pomoći vam da integrirate naše API-je u svoje projekte. Bilo da ste mali startup ili velika farmaceutska kompanija, naši API-ji mogu pružiti vrijedne informacije o našim visokokvalitetnim farmaceutskim sastojcima.

Reference

• OpenAPI specifikacijska dokumentacija
• Swagger.io - Alati i resursi za OpenAPI
• Dokumentacija poštara za testiranje API-ja