Swagger ва OpenAPI: API ҳужжатларини автоматлаштириш

Ҳар қандай бэкенд лойиҳада энг тез эскирадиган нарса — бу ҳужжатлар. Дастурчи янги endpoint қўшади, параметрни ўзгартиради ёки жавоб форматини соддалаштиради, аммо алоҳида сақланадиган ҳужжат эски ҳолатда қолади. Натижада фронтенд жамоаси ёки ташқи ҳамкорлар ишламайдиган мисоллар билан вақт йўқотади. Айнан шу муаммони ҳал қилиш учун OpenAPI стандарти ва Swagger экотизими пайдо бўлди: улар ҳужжатни алоҳида ҳужжат сифатида эмас, балки коднинг бир қисми сифатида кўради ва шу сабабли у доимо долзарб бўлиб қолади.

OpenAPI нима ва у қайси муаммони ечади

OpenAPI — бу REST API нинг бутун юзасини машина ўқий оладиган тарзда тасвирловчи стандарт спетсификация. Унда ҳар бир endpoint қайси манзилда жойлашгани, қайси HTTP методини қабул қилиши, қандай параметрларни кутиши ва қандай жавоб қайтариши аниқ ва расмий тилда ёзилади. Бу тавсиф одатда YAML ёки JSON файлида сақланади ва уни ҳам одам, ҳам дастур бир хил тушунади. Муҳим жиҳати шундаки, OpenAPI файли оддий текст ҳужжат эмас — у API нинг ягона ҳақиқат манбаи бўлиб хизмат қилади ва ундан кейинчалик ҳужжат, тест, мижоз кутубхонаси ва ҳатто сервер қолиплари автоматик тарзда ҳосил қилиниши мумкин.

Swagger нима ва OpenAPI билан қандай боғлиқ

Кўпчилик Swagger ва OpenAPI номларини бир хил нарса деб ўйлайди, аммо орада нозик фарқ бор. Swagger — бу OpenAPI стандартининг она авлоди бўлиб, кейинчалик стандарт OpenAPI Initiative номи остида мустақил бўлди, лекин Swagger номи воситалар тўплами сифатида сақланиб қолди. Бугун OpenAPI деганда спетсификациянинг ўзи, Swagger деганда эса шу спетсификация билан ишлайдиган амалий воситалар тушунилади: Swagger UI жонли ҳужжат чизади, Swagger Editor файлни таҳрирлаш имконини беради, Swagger Codegen эса ундан код ҳосил қилади. Бошқача айтганда, OpenAPI — бу тил, Swagger эса шу тилда гаплашадиган асбоблар.

Нега бу комбинация керак

Анъанавий ҳужжатларнинг асосий дарди — улар код билан синхрон юрмайди. OpenAPI ёндашуви бу муаммони илдиздан кесади, чунки спетсификация коднинг ёнида яшайди ва кўп ҳолларда ундан автоматик чиқарилади. Бундан ташқари, Swagger UI орқали яратилган ҳужжат шунчаки ўқиладиган эмас, балки синаладиган бўлади: дастурчи браузерда бевосита сўров юбориб, реал жавобни кўриши мумкин. Бу фронтенд ва бэкенд жамоалари ўртасидаги мулоқотни кескин тезлаштиради ва Postman каби алоҳида воситаларга бўлган эҳтиёжни камайтиради.

OpenAPI файлининг тузилмаси

OpenAPI файлининг асосий қисмлари оддий: умумий маълумот блоки, endpointлар рўйхати ва қайта ишлатиладиган маълумот схемалари. Қуйидаги қисқа мисол битта фойдаланувчини ID бўйича қайтарувчи endpointни тасвирлайди. Бу ерда диққат қилинг: параметр ҳам, муваффақиятли жавоб ҳам, жавоб ичидаги маълумот тузилмаси ҳам аниқ белгиланган.

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Бу файлдан кейинчалик Swagger UI чиройли интерфейс чизади, код генераторлари эса мижоз кутубхонасини яратади. Эътибор беринг, User схемаси алоҳида ажратилган ва $ref орқали боғланган — бу такрорланишни олдини олади ва катта лойиҳаларда тузилмани тоза сақлайди.

Koddan автоматик генерация — аннотациялар ёрдамида

YAML файлни қўлда ёзиш кичик лойиҳаларда қулай, аммо катта APIларда у тез эскиради. Шу сабабли кўплаб жамоалар тескари йўлни танлайди: спетсификацияни коднинг ўзидан, аннотациялар ёки махсус кутубхоналар ёрдамида автоматик ҳосил қилади. Масалан, PHPда Swagger-PHP кутубхонаси контроллер устидаги изоҳлардан тўлиқ OpenAPI файлини қуради, шунинг учун дастурчи endpointни ўзгартирганда ҳужжат ҳам ўз-ўзидан янгиланади.

/**
 * @OA\Get(
 *   path="/api/users/{id}",
 *   summary="Get user",
 *   @OA\Parameter(
 *     name="id", in="path", required=true,
 *     @OA\Schema(type="integer")
 *   ),
 *   @OA\Response(
 *     response=200, description="OK",
 *     @OA\JsonContent(ref="#/components/schemas/User")
 *   )
 * )
 */
public function show($id) {
    return User::findOrFail($id);
}

Бу ёндашувнинг гўзаллиги шундаки, ҳужжат ва мантиқ бир жойда — битта файлда — яшайди. Дастурчи параметрни янгилаганда ёнидаги аннотацияни ҳам янгилаши табиий бўлади, шунинг учун ҳужжат ҳеч қачон ҳақиқатдан ортда қолмайди. Node.js, Python ёки Javaда ҳам худди шундай кутубхоналар мавжуд ва ишлаш мантиғи деярли бир хил.

Swagger UI ва мижоз SDK генерацияси

OpenAPI файлидан олинадиган энг кўзга кўринадиган фойда — бу Swagger UI. У файлни ўқиб, ҳар бир endpoint учун интерактив саҳифа чизади, у ерда параметрларни киритиб, тугмани босиб, реал жавобни дарҳол кўриш мумкин. Бундан ҳам қимматлироқ жиҳат — код генерацияси: битта спетсификациядан ўнлаб дастурлаш тиллари учун мижоз кутубхоналари автоматик яратилади. Бу дегани, фронтенд жамоси ёки ташқи ҳамкор APIни қўлда ёзмайди, балки тайёр, типи текширилган SDKни ишлатади ва интеграция хатолари кескин камаяди.

Реал фойда ва хулоса

Амалиётда OpenAPI ва Swagger жуфти лойиҳанинг бутун ҳаёт тсиклини соддалаштиради. Янги дастурчи жамоага қўшилганда ҳужжатни ўқиб дарҳол ишлай бошлайди, фронтенд жамоси тайёр SDK орқали тез интеграция қилади, сифат назорати эса спетсификацияга асосланган автоматик тестлар ёзади. Энг муҳими — ҳужжат ва код бир манбадан келгани учун улар ҳеч қачон ажралиб кетмайди. Агар сиз янги бэкенд лойиҳа бошлаётган бўлсангиз, OpenAPIни биринчи кундан жорий этиш кейинчалик соатлаб қўлда ёзиш ва тушунмовчиликлардан қутқаради.