Kako dokumentirati API koristeći OpenAPI?

Bok tamo! Ja sam dobavljač API-ja (aktivni farmaceutski sastojak) i danas želim razgovarati o tome kako dokumentirati API pomoću OpenAPI-ja. To je iznimno važno u našem poslu jer jasna dokumentacija može učiniti ili uništiti uspjeh naših API-ja.

Prvo, shvatimo što je OpenAPI. OpenAPI je otvorena standardna specifikacija za opisivanje RESTful API-ja. Omogućuje način definiranja krajnjih točaka, operacija, ulaznih i izlaznih podataka i sigurnosnih zahtjeva API-ja u strojno čitljivom formatu. To znači da drugi programeri mogu lako razumjeti i integrirati naše API-je u svoje aplikacije.

Zašto je važno dokumentirati API-je pomoću OpenAPI-ja

Kao dobavljač API-ja, imamo hrpu sjajnih proizvoda poputMemantin hidroklorid丨CAS 41100 - 52 - 1,Dezoksimetazon 丨CAS 382-67-2, iGlutation丨CAS 70-18-8. Kako bismo našim klijentima olakšali pristup i korištenje ovih API-ja, neophodna je odgovarajuća dokumentacija.

Kada svoje API-je dokumentiramo s OpenAPI-jem, to pomaže na nekoliko načina. Kao prvo, omogućuje nam da jasno komuniciramo s našim klijentima o tome što naši API-ji mogu učiniti. Mogu točno vidjeti koje su krajnje točke dostupne, koje parametre trebaju proći i kakve odgovore mogu očekivati. Time se smanjuje broj pitanja i nesporazuma, što pak štedi vrijeme i nama i našim kupcima.

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

Početak rada s OpenAPI dokumentacijom

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

openapi: 3.0.0 info: title: Naš API za farmaceutske sastojke opis: Ovaj API pruža pristup informacijama o našim različitim aktivnim farmaceutskim sastojcima. verzija: 1.0.0 kontakt: ime: API podrška email: support@example.com

Zatim trebate definirati poslužitelje na kojima se nalazi API. Ovo programerima govori gdje zapravo mogu postavljati zahtjeve API-ju. Možete imati definirano više poslužitelja, na primjer, poslužitelj za proizvodnju i poslužitelj za testiranje.

poslužitelji: - url: https://api.example.com/v1 opis: proizvodni poslužitelj - url: https://test-api.example.com/v1 opis: testni poslužitelj

Definiranje API staza i operacija

Srce OpenAPI dokumenta je definicija API staza i operacija. Put 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 su GET, POST, PUT ili DELETE.

Recimo da imamo API koji pruža informacije o našim farmaceutskim sastojcima. Možda imamo put poput/sastojcikako biste dobili popis svih dostupnih sastojaka.

putevi: /sastojci: dobiti: sažetak: Dobiti popis svih farmaceutskih sastojaka opis: Vraća popis svih aktivnih farmaceutskih sastojaka koje nudimo. odgovori: '200': opis: popis sastojaka sadržaj: aplikacija/json: shema: tip: niz stavki: tip: svojstva objekta: naziv: tip: niz cas_number: tip: niz

U ovom smo primjeru definirali operaciju GET na/sastojciput. Sažetak i opis pružaju više informacija o tome što operacija radi. Odjeljak s odgovorima definira što će API vratiti kada je operacija 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 puta (dio URL-a) ili parametri tijela zahtjeva (poslani u tijelu zahtjeva).

Recimo da želimo dobiti informacije o određenom sastojku prema njegovom CAS broju. Za ovo možemo definirati parametar staze.

putevi: /ingredients/{cas_number}: get: summary: Dobivanje informacija o specifičnom sastojku opis: Vraća detaljne informacije o sastojku na temelju njegovog CAS broja. parametri: - ime: cas_number u: opis staze: CAS broj potrebnog sastojka: istinita shema: tip: niz odgovori: '200': opis: Informacije o sadržaju sastojka: aplikacija/json: shema: tip: svojstva objekta: naziv: tip: niz cas_number: tip: opis niza: tip: niz

U ovom smo primjeru definirali parametar stazecas_broju/sastojci/{cas_number}put. Thepotrebanpolje 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ćuje definiranje sigurnosnih zahtjeva 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 naziv: X - API - Key in: zaglavlje sigurnost: - api_key: []

U ovom smo primjeru definirali sigurnosnu shemu tzvapi_ključkoji koristi API ključ poslan uX - API - ključzaglavlje. Thesigurnostiodjeljak na najvišoj razini dokumenta pokazuje da sve operacije u API-ju zahtijevaju ovaj API ključ za provjeru autentičnosti.

Provjera valjanosti i testiranje OpenAPI dokumenta

Nakon što ste izradili svoj OpenAPI dokument, važno ga je potvrditi kako biste bili sigurni da slijedi OpenAPI specifikaciju. Dostupni su mnogi online alati koji vam u tome mogu pomoći. Također možete koristiti alate za generiranje koda klijenta iz OpenAPI dokumenta i testirati API.

Testiranje je ključno kako bi se osiguralo da se API ponaša prema očekivanjima. Možete koristiti alate kao što su Postman ili cURL za slanje zahtjeva API-ju i provjeru odgovora. Testiranjem API-ja s različitim ulaznim parametrima i scenarijima, možete rano uhvatiti sve pogreške ili probleme.

Zaključak i poziv na akciju

Dokumentiranje API-ja pomoću OpenAPI-ja moćan je način da svoj API učinite pristupačnijim i lakšim za korištenje. Kao dobavljaču API-ja, pomaže nam da bolje služimo našim klijentima i promoviramo korištenje naših proizvoda kao što suMemantin hidroklorid丨CAS 41100 - 52 - 1,Dezoksimetazon 丨CAS 382-67-2, iGlutation丨CAS 70-18-8.

Ako želite saznati više o našim API-jima ili imate 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 tvrtka, naši API-ji mogu pružiti vrijedne informacije o našim visokokvalitetnim farmaceutskim sastojcima.

Reference

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