M

MLOG

Suomi

Tutustu OpenAPI-määrittelyn (OAS) voimaan. Tämä opas kattaa kaiken peruskäsitteistä ja hyödyistä käytännön esimerkkeihin ja API-first-suunnittelun tulevaisuuteen.

API-dokumentaation evoluutio: Kattava opas OpenAPI-määrittelyyn

Nykypäivän hyperkytketyssä digitaalisessa maailmassa sovellusliittymät (API) ovat näkymättömiä lankoja, jotka kutovat ohjelmistomme ja palvelumme yhteen. Ne ovat modernin digitaalitalouden moottori, joka mahdollistaa kaiken mobiilipankkitoiminnoista sosiaalisen median syötteisiin. Mutta kun API-liittymien määrä räjähtää, esiin nousee kriittinen haaste: miten kehittäjät, järjestelmät ja organisaatiot voivat kommunikoida tehokkaasti ja ilman epäselvyyksiä? Kuinka varmistamme, että toisella puolella maailmaa rakennettu API voidaan saumattomasti ottaa käyttöön toisella puolella maailmaa olevassa palvelussa?

Vastaus piilee yhteisessä kielessä, universaalissa sopimuksessa, joka kuvaa API:n kyvykkyydet tavalla, jonka sekä ihmiset että koneet voivat ymmärtää. Tämä on OpenAPI-määrittelyn (OAS) rooli. Enemmän kuin pelkkä dokumentaatio, OAS on perustavanlaatuinen standardi RESTful-APIen suunnitteluun, rakentamiseen, dokumentointiin ja käyttämiseen. Tämä opas vie sinut syvälle OpenAPI-määrittelyyn, tutkien mitä se on, miksi se on tärkeä ja miten voit hyödyntää sitä parempien ja yhteistyökykyisempien digitaalisten tuotteiden rakentamisessa.

Mitä on OpenAPI-määrittely? Universaali kieli API-liittymille

Ytimeltään OpenAPI-määrittely on standardoitu, kieliriippumaton rajapintakuvaus RESTful-API-liittymille. Sen avulla voit määrittää koko API:si rakenteen yhdessä tiedostossa, joka on tyypillisesti kirjoitettu joko YAML- tai JSON-muodossa. Ajattele sitä rakennuksen yksityiskohtaisena piirustuksena; ennen rakentamisen aloittamista piirustus hahmottelee jokaisen huoneen, oven ja pistorasian. Vastaavasti OpenAPI-dokumentti kuvaa:

Lyhyt historia: Swaggerista OpenAPI:ksi

Olet ehkä kuullut termin "Swagger" käytettävän synonyymina OpenAPI:lle. On tärkeää ymmärtää niiden suhde. Määrittely sai alkunsa Swagger-määrittelynä vuonna 2010, jonka loi Tony Tam Reverb-yrityksessä. Sen saavuttaessa valtavan suosion, se lahjoitettiin Linux Foundationille vuonna 2015 ja nimettiin uudelleen OpenAPI-määrittelyksi, mikä vakiinnutti sen aidoksi avoimeksi standardiksi OpenAPI Initiativen johdolla. OpenAPI Initiative on teollisuuden johtajien, kuten Googlen, Microsoftin ja IBM:n, muodostama konsortio.

Nykyään Swagger viittaa tehokkaiden avoimen lähdekoodin ja ammattimaisten työkalujen sarjaan, jotka toimivat OpenAPI-määrittelyn kanssa, kuten Swagger UI interaktiivisen dokumentaation luomiseen ja Swagger Editor itse määrittelyn kirjoittamiseen.

OpenAPI-dokumentin ydinkomponentit

OpenAPI-dokumentti on jäsennelty tietyillä kentillä. Vaikka se voi aluksi näyttää pelottavalta, se on loogisesti järjestetty. Käydään läpi OpenAPI 3.x -dokumentin keskeiset rakennuspalikat käyttäen YAML-muotoa sen paremman ihmisluettavuuden vuoksi.

1. `openapi`- ja `info`-objektit: Perusteet

Jokainen OpenAPI-dokumentti alkaa versiolla ja olennaisilla metatiedoilla.

Esimerkki:


openapi: 3.0.3
info:
  title: Globaali Kirjaluettelo API
  description: API, jolla voi käyttää maailmanlaajuista kirjaluetteloa.
  version: 1.0.0
  contact:
    name: API-tukitiimi
    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`-taulukko: Mistä API:si löytyy

servers-taulukko määrittää API:si perus-URL-osoitteet. Voit määrittää useita palvelimia eri ympäristöille, kuten kehitys-, staging- ja tuotantoympäristöille. Tämä mahdollistaa työkalujen helpon vaihtamisen ympäristöjen välillä.

Esimerkki:


servers:
  - url: https://api.example.com/v1
    description: Tuotantopalvelin
  - url: https://staging-api.example.com/v1
    description: Staging-palvelin

3. `paths`-objekti: API:n sydän

Tässä määritellään API:n päätepisteet. paths-objekti sisältää kaikki yksittäiset URL-polut. Jokainen polku kuvaa sitten HTTP-operaatiot (get, post, put, delete, jne.), jotka voidaan suorittaa kyseisellä polulla.

Jokaisen operaation sisällä määritellään yksityiskohtia, kuten:

4. `components`-objekti: Uudelleenkäytettävät rakennuspalikat

Välttääksesi itsesi toistamista (DRY-periaatteen mukaisesti), OpenAPI tarjoaa components-objektin. Tämä on tehokas ominaisuus, jossa voit määrittää uudelleenkäytettäviä elementtejä ja viitata niihin koko määrittelyssäsi käyttämällä $ref-osoittimia.

5. `security`-objekti: Tunnistautumisen soveltaminen

Kun olet määrittänyt securitySchemes-komponentit, security-objektia käytetään niiden soveltamiseen. Voit soveltaa suojausta globaalisti koko API:lle tai operaatiokohtaisesti, mikä mahdollistaa julkisten ja suojattujen päätepisteiden sekoituksen.

Miksi organisaatiosi tulisi ottaa OpenAPI käyttöön: Liiketoiminnalliset ja tekniset hyödyt

OpenAPI-määrittelyn käyttöönotto ei ole vain tekninen valinta; se on strateginen päätös, joka lisää tehokkuutta, yhteistyötä ja laatua koko ohjelmistokehityksen elinkaaren ajan.

Kehittäjille: Yksi totuuden lähde

Tuotepäälliköille ja arkkitehdeille: Suunnittelu ja hallinta

Testaajille ja laadunvarmistustiimeille: Virtaviivaistettu validointi

Loppukäyttäjille ja kumppaneille: Ylivoimainen kehittäjäkokemus (DX)

Käytännön opas: Ensimmäisen OpenAPI-dokumentin luominen

Laitetaan teoria käytäntöön luomalla perusmuotoinen OpenAPI 3.0 -määrittely meidän "Globaali Kirjaluettelo API" -liittymällemme. Käytämme YAML-muotoa sen luettavuuden vuoksi.

Vaihe 1: Määritä perustiedot ja palvelimet

Aloitamme metatiedoilla ja tuotantopalvelimen URL-osoitteella.


openapi: 3.0.3
info:
  title: Globaali Kirjaluettelo API
  description: API, jolla voi käyttää maailmanlaajuista kirjaluetteloa.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

Vaihe 2: Määritä uudelleenkäytettävä datamalli `components`-osiossa

Ennen päätepisteiden määrittelyä, luodaan uudelleenkäytettävä skeema Book-objektille. Tämä pitää suunnitelmamme siistinä ja johdonmukaisena.


components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: Kansainvälinen standardikirjanumero.
          example: '978-0321765723'
        title:
          type: string
          description: Kirjan nimi.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: Kirjan kirjoittaja.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: Kirjan julkaisuvuosi.
          example: 2013
      required:
        - isbn
        - title
        - author

Vaihe 3: Määritä päätepisteet `paths`-osiossa

Nyt luomme kaksi päätepistettä: yhden kirjojen listan hakemiseen ja toisen tietyn kirjan hakemiseen sen ISBN-numerolla.

Huomaa viittauksen $ref: '#/components/schemas/Book' käyttö. Näin viittaamme uudelleenkäytettävään Book-skeemaamme.


paths:
  /books:
    get:
      summary: Listaa kaikki saatavilla olevat kirjat
      description: Palauttaa listan kirjoista, valinnaisesti suodatettuna.
      operationId: listBooks
      responses:
        '200':
          description: Onnistunut vastaus, joka sisältää taulukon kirjoja.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: Hae kirja sen ISBN-numerolla
      description: Palauttaa yhden kirjan sen ISBN-numeron perusteella.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: Noudettavan kirjan ISBN-numero.
          schema:
            type: string
      responses:
        '200':
          description: Pyydetty kirja.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Määritetyllä ISBN-numerolla varustettua kirjaa ei löytynyt.

Vaihe 4: Lisää suojaus

Suojataan API:mme yksinkertaisella API-avaimella, joka on lähetettävä otsakkeessa. Ensin määritämme skeeman components-osiossa, sitten sovellamme sitä globaalisti.


# Lisää tämä 'components'-osioon
components:
  # ... aiemmat skeemat
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# Lisää tämä dokumentin juuritasolle
security:
  - ApiKeyAuth: []

Vaihe 5: Validoi ja visualisoi

Kun YAML-tiedostosi on valmis, voit käyttää erilaisia työkaluja:

OpenAPI-ekosysteemi: Työkalut ja teknologiat

OAS:n voimaa vahvistaa sen laaja ja kypsä työkaluekosysteemi. Mihin tahansa tarpeeseen, sille on todennäköisesti olemassa työkalu:

OpenAPI:n tulevaisuus: OAS 3.1 ja sen jälkeen

OpenAPI-määrittely kehittyy jatkuvasti. Viimeisin suuri versio, OAS 3.1, esitteli useita merkittäviä parannuksia:

Nämä edistysaskeleet vahvistavat OpenAPI:n asemaa keskeisenä artefaktina modernissa, API-first- ja tapahtumapohjaisessa arkkitehtuurissa.

Johtopäätös: Modernin kehityksen kulmakivi

OpenAPI-määrittely on muuttanut tapaamme ajatella API-liittymiä. Se on nostanut API-dokumentaation pelätystä, usein laiminlyödystä jälkityöstä strategiseksi, eläväksi dokumentiksi, joka ohjaa koko kehityksen elinkaarta. Toimimalla koneellisesti luettavana sopimuksena OAS edistää yhteistyötä, mahdollistaa tehokkaan automaation, valvoo yhdenmukaisuutta ja johtaa lopulta parempien, luotettavampien ja helpommin käytettävien API-liittymien luomiseen.

Olitpa sitten kehittäjä, arkkitehti, tuotepäällikkö tai testaaja, OpenAPI-määrittelyn omaksuminen on kriittinen askel kohti modernin ohjelmistokehityksen hallintaa. Jos et vielä käytä sitä, harkitse sen aloittamista seuraavassa projektissasi. Määrittele sopimus ensin, jaa se tiimisi kanssa ja avaa uusi tehokkuuden ja selkeyden taso digitaalisissa yhteistyöprojekteissasi.