M

MLOG

Български

Открийте силата на спецификацията OpenAPI (OAS). Това ръководство обхваща всичко – от основни концепции и предимства до практически примери и бъдещето на API-first дизайна.

Еволюцията на API документацията: Цялостно ръководство за спецификацията OpenAPI

В днешния хиперсвързан дигитален свят интерфейсите за програмиране на приложения (API) са невидимите нишки, които свързват нашия софтуер и услуги. Те са двигателят на съвременната дигитална икономика, позволявайки всичко – от мобилно банкиране до емисии в социалните медии. Но с експлозивното нарастване на броя на API-тата възниква критично предизвикателство: как разработчици, системи и организации могат да комуникират ефективно и без двусмислици? Как да гарантираме, че API, създадено в една част на света, може безпроблемно да бъде използвано от услуга в друга?

Отговорът се крие в общ език, универсален договор, който описва възможностите на дадено API по начин, разбираем както за хора, така и за машини. Това е ролята на спецификацията OpenAPI (OAS). Повече от просто документация, OAS е основополагащ стандарт за проектиране, изграждане, документиране и използване на RESTful API-та. Това ръководство ще ви потопи дълбоко в спецификацията OpenAPI, изследвайки какво представлява тя, защо е важна и как можете да я използвате, за да създавате по-добри и по-съвместни дигитални продукти.

Какво е спецификацията OpenAPI? Универсален език за API

В своята същност спецификацията OpenAPI е стандартен, независим от езика интерфейсен дескриптор за RESTful API-та. Тя ви позволява да дефинирате цялата структура на вашето API в един-единствен файл, обикновено написан на YAML или JSON. Представете си го като подробен план на сграда; преди да започне строителството, планът очертава всяка стая, всяка врата и всеки електрически контакт. По подобен начин OpenAPI документът описва:

Кратка история: От Swagger до OpenAPI

Може би сте чували терминът „Swagger“ да се използва взаимозаменяемо с OpenAPI. Важно е да се разбере връзката им. Спецификацията започва като Swagger Specification през 2010 г., създадена от Тони Там в Reverb. Тъй като придобива огромна популярност, тя е дарена на Linux Foundation през 2015 г. и е преименувана на OpenAPI Specification, утвърждавайки се като истински отворен стандарт под ръководството на OpenAPI Initiative, консорциум от лидери в индустрията, включващ Google, Microsoft и IBM.

Днес Swagger се отнася до набор от мощни инструменти с отворен код и професионални такива, които работят със спецификацията OpenAPI, като например Swagger UI за генериране на интерактивна документация и Swagger Editor за писане на самата спецификация.

Основни компоненти на OpenAPI документ

Един OpenAPI документ е структуриран с набор от специфични полета. Въпреки че на пръв поглед може да изглежда плашещо, той е логично организиран. Нека разгледаме ключовите градивни елементи на OpenAPI 3.x документ, използвайки YAML заради по-добрата му четимост от хора.

1. Обектите `openapi` и `info`: Основите

Всеки OpenAPI документ започва с версия и съществени метаданни.

Пример:


openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: API за достъп до каталог с книги от цял свят.
  version: 1.0.0
  contact:
    name: Екип за поддръжка на API
    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`: Къде да намерите вашето API

Масивът servers указва базовите URL адреси за вашето API. Можете да дефинирате множество сървъри за различни среди, като например за разработка, стейджинг и продукция. Това позволява на инструментите лесно да превключват между средите.

Пример:


servers:
  - url: https://api.example.com/v1
    description: Продукционен сървър
  - url: https://staging-api.example.com/v1
    description: Стейджинг сървър

3. Обектът `paths`: Сърцето на API

Тук дефинирате крайните точки на вашето API. Обектът paths съдържа всички индивидуални URL пътища. Всеки елемент на пътя след това описва HTTP операциите (get, post, put, delete и т.н.), които могат да бъдат извършени на този път.

В рамките на всяка операция дефинирате детайли като:

4. Обектът `components`: Компоненти за многократна употреба

За да избегнете повторения (следвайки принципа DRY - Don't Repeat Yourself), OpenAPI предоставя обекта components. Това е мощна функция, където можете да дефинирате елементи за многократна употреба и да ги препращате в цялата си спецификация, използвайки указатели $ref.

5. Обектът `security`: Прилагане на удостоверяване

След като сте дефинирали вашите securitySchemes в компонентите, обектът security се използва за тяхното прилагане. Можете да приложите сигурност глобално за цялото API или за всяка операция поотделно, което позволява комбинация от публични и защитени крайни точки.

Защо вашата организация трябва да приеме OpenAPI: Бизнес и технически предимства

Приемането на спецификацията OpenAPI не е просто технически избор; това е стратегическо решение, което стимулира ефективността, сътрудничеството и качеството през целия жизнен цикъл на разработката на софтуер.

За разработчиците: Единственият източник на истина

За продуктови мениджъри и архитекти: Дизайн и управление

За тестъри и QA екипи: Опростена валидация

За крайни потребители и партньори: Превъзходно изживяване за разработчици (DX)

Практическо ръководство: Създаване на първия ви OpenAPI документ

Нека приложим теорията на практика, като създадем основна спецификация OpenAPI 3.0 за нашето „API за глобален каталог на книги“. Ще използваме YAML заради неговата четимост.

Стъпка 1: Дефиниране на основна информация и сървъри

Започваме с метаданните и URL адреса на продукционния сървър.


openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: API за достъп до каталог с книги от цял свят.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

Стъпка 2: Дефиниране на модел на данни за многократна употреба в `components`

Преди да дефинираме нашите крайни точки, нека създадем схема за многократна употреба за обект `Book`. Това поддържа нашия дизайн чист и последователен.


components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: Международният стандартен номер на книга.
          example: '978-0321765723'
        title:
          type: string
          description: Заглавието на книгата.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: Авторът на книгата.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: Годината на публикуване на книгата.
          example: 2013
      required:
        - isbn
        - title
        - author

Стъпка 3: Дефиниране на крайните точки в `paths`

Сега ще създадем две крайни точки: една за получаване на списък с книги и друга за получаване на конкретна книга по нейния ISBN.

Обърнете внимание на използването на $ref: '#/components/schemas/Book'. Така препращаме към нашата схема `Book` за многократна употреба.


paths:
  /books:
    get:
      summary: Изброяване на всички налични книги
      description: Връща списък с книги, с възможност за филтриране.
      operationId: listBooks
      responses:
        '200':
          description: Успешен отговор с масив от книги.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: Получаване на книга по нейния ISBN
      description: Връща една книга, идентифицирана по нейния ISBN.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: ISBN на книгата, която да бъде извлечена.
          schema:
            type: string
      responses:
        '200':
          description: Заявената книга.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Книгата с посочения ISBN не е намерена.

Стъпка 4: Добавяне на сигурност

Нека защитим нашето API с прост API ключ, който трябва да бъде изпратен в хедър. Първо, дефинираме схемата в `components`, след което я прилагаме глобално.


# Добавете това към секцията 'components'
components:
  # ... схемите отпреди
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# Добавете това на основно ниво в документа
security:
  - ApiKeyAuth: []

Стъпка 5: Валидиране и визуализиране

С вашия пълен YAML файл вече можете да използвате различни инструменти:

Екосистемата на OpenAPI: Инструменти и технологии

Силата на OAS се подсилва от нейната огромна и зряла екосистема от инструменти. Каквато и да е вашата нужда, вероятно има инструмент за нея:

Бъдещето на OpenAPI: OAS 3.1 и отвъд

Спецификацията OpenAPI непрекъснато се развива. Последната голяма версия, OAS 3.1, въведе няколко значителни подобрения:

Тези подобрения утвърждават позицията на OpenAPI като централен артефакт в една модерна, API-first и управлявана от събития архитектура.

Заключение: Крайъгълен камък на модерната разработка

Спецификацията OpenAPI промени начина, по който мислим за API-тата. Тя издигна API документацията от ужасяваща, често пренебрегвана задача до стратегически, жив документ, който движи целия жизнен цикъл на разработката. Служейки като машинночетим договор, OAS насърчава сътрудничеството, дава възможност за мощна автоматизация, налага последователност и в крайна сметка води до създаването на по-добри, по-надеждни и по-лесно използваеми API-та.

Независимо дали сте разработчик, архитект, продуктов мениджър или тестър, възприемането на спецификацията OpenAPI е критична стъпка към овладяването на модерната разработка на софтуер. Ако все още не я използвате, обмислете да започнете със следващия си проект. Дефинирайте договора първо, споделете го с екипа си и отключете ново ниво на ефективност и яснота във вашите дигитални сътрудничества.