M

MLOG

Lietuvių

Atraskite OpenAPI specifikacijos (OAS) galią. Šis vadovas apima viską – nuo pagrindinių koncepcijų ir privalumų iki praktinių pavyzdžių ir API-first dizaino ateities.

API dokumentacijos evoliucija: išsamus OpenAPI specifikacijos vadovas

Šiuolaikiniame itin susietame skaitmeniniame pasaulyje programų sąsajos (API) yra nematomos gijos, jungiančios mūsų programinę įrangą ir paslaugas. Jos yra modernios skaitmeninės ekonomikos variklis, leidžiantis veikti viskam – nuo mobiliosios bankininkystės iki socialinių tinklų naujienų srautų. Tačiau, sparčiai augant API skaičiui, kyla esminis iššūkis: kaip programuotojai, sistemos ir organizacijos gali bendrauti efektyviai ir be dviprasmybių? Kaip užtikrinti, kad viename pasaulio krašte sukurta API galėtų būti sklandžiai naudojama paslaugos kitame?

Atsakymas slypi bendroje kalboje, universaliame kontrakte, kuris aprašo API galimybes taip, kad suprastų tiek žmonės, tiek mašinos. Tai yra OpenAPI specifikacijos (OAS) vaidmuo. Tai daugiau nei tik dokumentacija – OAS yra pagrindinis standartas, skirtas RESTful API projektavimui, kūrimui, dokumentavimui ir naudojimui. Šis vadovas jus išsamiai supažindins su OpenAPI specifikacija, paaiškins, kas tai yra, kodėl tai svarbu ir kaip galite ją panaudoti kurdami geresnius, labiau bendradarbiavimu pagrįstus skaitmeninius produktus.

Kas yra OpenAPI specifikacija? Universali kalba API sąsajoms

Iš esmės OpenAPI specifikacija yra standartizuotas, nuo programavimo kalbos nepriklausomas RESTful API sąsajų aprašas. Ji leidžia apibrėžti visą API struktūrą viename faile, paprastai parašytame YAML arba JSON formatu. Įsivaizduokite tai kaip detalų pastato brėžinį; prieš pradedant bet kokias statybas, brėžinyje nurodomas kiekvienas kambarys, kiekvienos durys ir kiekvienas elektros lizdas. Panašiai OpenAPI dokumentas aprašo:

Trumpa istorija: nuo „Swagger“ iki „OpenAPI“

Galbūt girdėjote terminą „Swagger“, vartojamą kaip „OpenAPI“ sinonimą. Svarbu suprasti jų ryšį. Specifikacija pradėjo savo kelią kaip „Swagger“ specifikacija 2010 m., sukurta Tony Tam iš „Reverb“. Jai įgavus didžiulį populiarumą, 2015 m. ji buvo perduota „Linux Foundation“ ir pervadinta į OpenAPI specifikaciją, taip įtvirtinant ją kaip tikrą atvirą standartą, kurį globoja „OpenAPI Initiative“ – pramonės lyderių, tokių kaip „Google“, „Microsoft“ ir IBM, konsorciumas.

Šiandien Swagger reiškia galingų atvirojo kodo ir profesionalių įrankių rinkinį, veikiantį su OpenAPI specifikacija, pavyzdžiui, „Swagger UI“ interaktyviai dokumentacijai generuoti ir „Swagger Editor“ pačiai specifikacijai rašyti.

Pagrindiniai OpenAPI dokumento komponentai

OpenAPI dokumentas yra struktūrizuotas naudojant specifinių laukų rinkinį. Nors iš pirmo žvilgsnio tai gali atrodyti bauginančiai, jis yra logiškai sutvarkytas. Panagrinėkime pagrindinius OpenAPI 3.x dokumento elementus, naudodami YAML formatą dėl jo geresnio skaitomumo žmonėms.

1. `openapi` ir `info` objektai: pagrindai

Kiekvienas OpenAPI dokumentas prasideda nuo versijos ir esminių metaduomenų.

Pavyzdys:


openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
  contact:
    name: API Support Team
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

2. `servers` masyvas: kur rasti jūsų API

servers masyvas nurodo pagrindinius jūsų API URL adresus. Galite apibrėžti kelis serverius skirtingoms aplinkoms, tokioms kaip kūrimo, testavimo (staging) ir gamybos (production). Tai leidžia įrankiams lengvai perjungti aplinkas.

Pavyzdys:


servers:
  - url: https://api.example.com/v1
    description: Production Server
  - url: https://staging-api.example.com/v1
    description: Staging Server

3. `paths` objektas: API šerdis

Čia apibrėžiami jūsų API galiniai taškai. paths objektas saugo visus individualius URL kelius. Kiekvienas kelio elementas tada aprašo HTTP operacijas (get, post, put, delete ir kt.), kurias galima atlikti su tuo keliu.

Kiekvienoje operacijoje apibrėžiate tokias detales kaip:

4. `components` objektas: pernaudojami elementai

Siekdama išvengti pasikartojimo (laikantis DRY principo), OpenAPI suteikia components objektą. Tai galinga funkcija, kurioje galite apibrėžti pernaudojamus elementus ir juos nurodyti visoje specifikacijoje naudodami $ref nuorodas.

5. `security` objektas: autentifikacijos taikymas

Kai apibrėžėte savo securitySchemes komponentuose, security objektas yra naudojamas joms pritaikyti. Galite taikyti saugumą globaliai visai API arba kiekvienai operacijai atskirai, leidžiant derinti viešus ir apsaugotus galinius taškus.

Kodėl jūsų organizacija turėtų priimti OpenAPI: verslo ir techniniai privalumai

OpenAPI specifikacijos priėmimas yra ne tik techninis pasirinkimas; tai strateginis sprendimas, kuris skatina efektyvumą, bendradarbiavimą ir kokybę visame programinės įrangos kūrimo cikle.

Programuotojams: vienintelis tiesos šaltinis

Produktų vadovams ir architektams: projektavimas ir valdymas

Testuotojams ir kokybės užtikrinimo komandoms: supaprastintas patvirtinimas

Galutiniams vartotojams ir partneriams: geresnė programuotojų patirtis (DX)

Praktinis vadovas: pirmojo OpenAPI dokumento kūrimas

Pritaikykime teoriją praktikoje, sukurdami pagrindinę OpenAPI 3.0 specifikaciją mūsų „Pasauliniam knygų katalogui“. Naudosime YAML dėl jo skaitomumo.

1 žingsnis: apibrėžkite pagrindinę informaciją ir serverius

Pradedame nuo metaduomenų ir gamybos serverio URL.


openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

2 žingsnis: apibrėžkite pernaudojamą duomenų modelį `components` dalyje

Prieš apibrėždami galinius taškus, sukurkime pernaudojamą schemą `Book` (knygos) objektui. Tai padės išlaikyti mūsų dizainą švarų ir nuoseklų.


components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: The International Standard Book Number.
          example: '978-0321765723'
        title:
          type: string
          description: The title of the book.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: The author of the book.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: The year the book was published.
          example: 2013
      required:
        - isbn
        - title
        - author

3 žingsnis: apibrėžkite galinius taškus `paths` dalyje

Dabar sukursime du galinius taškus: vieną, skirtą gauti knygų sąrašą, ir kitą, skirtą gauti konkrečią knygą pagal jos ISBN.

Atkreipkite dėmesį į $ref: '#/components/schemas/Book' naudojimą. Taip mes nurodome savo pernaudojamą `Book` schemą.


paths:
  /books:
    get:
      summary: List all available books
      description: Returns a list of books, optionally filtered.
      operationId: listBooks
      responses:
        '200':
          description: A successful response with an array of books.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: Get a book by its ISBN
      description: Returns a single book identified by its ISBN.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: The ISBN of the book to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: The requested book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: The book with the specified ISBN was not found.

4 žingsnis: pridėkite saugumą

Apsaugokime savo API paprastu API raktu, kuris turi būti siunčiamas antraštėje. Pirmiausia, apibrėžiame schemą `components` dalyje, tada ją taikome globaliai.


# Add this to the 'components' section
components:
  # ... schemas from before
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# Add this at the root level of the document
security:
  - ApiKeyAuth: []

5 žingsnis: patvirtinkite ir vizualizuokite

Turėdami pilną YAML failą, dabar galite naudoti įvairius įrankius:

OpenAPI ekosistema: įrankiai ir technologijos

OAS galią sustiprina jos plati ir brandi įrankių ekosistema. Kad ir koks būtų jūsų poreikis, tikėtina, kad tam yra įrankis:

OpenAPI ateitis: OAS 3.1 ir vėlesnės versijos

OpenAPI specifikacija nuolat tobulėja. Naujausia pagrindinė versija, OAS 3.1, pristatė keletą reikšmingų patobulinimų:

Šie patobulinimai įtvirtina OpenAPI poziciją kaip centrinį artefaktą modernioje, „API-first“ ir įvykiais pagrįstoje architektūroje.

Išvada: šiuolaikinio programavimo kertinis akmuo

OpenAPI specifikacija pakeitė mūsų požiūrį į API. Ji pakėlė API dokumentaciją nuo baimę keliančios, dažnai apleistos antraeilės užduoties iki strateginio, gyvo dokumento, kuris skatina visą kūrimo ciklą. Veikdama kaip mašininiu būdu skaitomas kontraktas, OAS skatina bendradarbiavimą, įgalina galingą automatizavimą, užtikrina nuoseklumą ir galiausiai veda prie geresnių, patikimesnių ir lengviau naudojamų API kūrimo.

Nesvarbu, ar esate programuotojas, architektas, produkto vadovas ar testuotojas, OpenAPI specifikacijos priėmimas yra esminis žingsnis siekiant įvaldyti šiuolaikinį programinės įrangos kūrimą. Jei dar jos nenaudojate, apsvarstykite galimybę pradėti nuo kito savo projekto. Pirmiausia apibrėžkite kontraktą, pasidalykite juo su savo komanda ir atraskite naują efektyvumo ir aiškumo lygį savo skaitmeniniame bendradarbiavime.