OpenAPI

OpenAPI — HTTP API tuzilishini mashina va inson o‘qiy oladigan shaklda tavsiflash uchun ishlatiladigan ochiq spetsifikatsiyadir. Hujjat endpointlar, parametrlar, request body, response, autentifikatsiya va ma’lumot sxemalarini YAML yoki JSON formatida ifodalaydi. OpenAPI dastur kodi emas; u API shartnomasini tasvirlaydi va turli vositalar shu tavsifdan hujjat, client yoki test hosil qilishi mumkin.

Hujjat tuzilishi

OpenAPI hujjatining yuqori qismida spetsifikatsiya versiyasi, API nomi va serverlar beriladi. paths har URL path va HTTP methodni, components esa qayta ishlatiladigan schema, parameter, response va security schemalarini saqlaydi.

openapi: 3.1.0
info:
  title: Articles API
  version: 1.0.0
paths:
  /articles/{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Maqola topildi

Path parametri required bo‘lishi kerak. Query, header va cookie parametrlar ham in maydoni orqali ajratiladi.

Schema

Schema obyekt, array, string, number va boshqa ma’lumot shakllarini belgilaydi. Required maydonlar, format, enum, minimum va pattern kabi cheklovlar validatsiya va client generationda ishlatiladi. $ref bir schema ta’rifini ko‘p endpointda takrorlamasdan ulaydi.

OpenAPI 3.1 JSON Schema bilan yaqinroq moslashgan. Spetsifikatsiya versiyasi vosita qo‘lloviga mos bo‘lishi kerak; 3.0 va 3.1dagi ayrim schema xususiyatlari bir xil talqin qilinmaydi.

Request va response

requestBody content type bo‘yicha body sxemasini tavsiflaydi. Masalan, JSON va multipart upload alohida media type sifatida beriladi. Responses status code bo‘yicha body va headerlarni ko‘rsatadi. Faqat 200ni yozish API xato shartnomasini yashiradi; keng tarqalgan 400, 401, 404 va boshqa natijalar ham hujjatlashtiriladi.

Xavfsizlik sxemalari

API key, HTTP Basic, Bearer token va OAuth 2.0 kabi usullar securitySchemes ichida belgilanadi. Global security barcha endpointga, operation darajasidagi security esa muayyan endpointga qo‘llanadi. Sxema tokenni qanday tekshirish yoki permissionni qanday hisoblashni amalga oshirmaydi; u clientga autentifikatsiya usulini bildiradi.

Code-first va design-first

Code-first yondashuvda framework route va model kodidan OpenAPI hujjatini yaratadi. Bu real kod bilan yaqinlik beradi, ammo yetarli annotation bo‘lmasa ma’no va misollar kambag‘al qoladi. Design-firstda shartnoma avval yoziladi, server va client undan hosil qilinadi yoki unga mos ishlab chiqiladi.

CI jarayoni hujjatni lint qiladi, breaking change aniqlaydi va server javobini schema bilan solishtirishi mumkin. Generated client qo‘lda tekshirilmasdan mutlaq to‘g‘ri deb qabul qilinmaydi; naming, nullable semantikasi va tilga xos turlar natijaga ta’sir qiladi.

Polymorphism va misollar

oneOf, anyOf va allOf schema variantlarini ifodalaydi. oneOf qiymat aynan bitta variantga mosligini, anyOf kamida bittasiga mosligini bildiradi; allOf bir nechta schema talabini birlashtiradi. Discriminator obyekt ichidagi maydon asosida qaysi variant tanlanishini ko‘rsatishi mumkin. Turli generatorlar murakkab polymorphismni bir xil qo‘llamasligi sababli clientlar bilan sinov kerak. example hujjatda realistik payload ko‘rsatadi, lekin schema validatsiyasining o‘rnini bosmaydi. Maxfiy token, haqiqiy shaxsiy ma’lumot yoki ishlab chiqarish hosti misolga kiritilmaydi.

Operation ID har endpoint uchun barqaror va yagona bo‘lsa, generated client metodlari tushunarli nom oladi. Uni o‘zgartirish client kodida breaking change bo‘lishi mumkin.

Bog‘liq tushunchalar

API specification, JSON Schema, Swagger UI, REST, endpoint, code generation, API documentation