OpenAPI

Матеріал з Вікіпедії — вільної енциклопедії.
Перейти до навігації Перейти до пошуку
Специфікація API української вікіпедії, відображена в Swagger UI, з прикладом запиту

Специфікація OpenAPI, початково відома як Swagger - це специфікація машиночитабельних файлів з інтерфейсами, для опису, створення, використання і візуалізації REST веб сервісів.[1] Існують різноманітні інструменти що можуть генерувати код, документацію і тести за файлом з описом інтерфейсу. За розробкою специфікації OpenAPI (OAS) наглядає Open API Initiative, проект Linux Foundation.[2]

Історія[ред. | ред. код]

Розробка Swagger почалась в 2010. В березні 2015, SmartBear Software купила Swagger API specification у Reverb Technologies.[3] В листопаді 2015, SmartBear, компанія яка підтримувала специфікацію Swagger та пов'язані інструменти, оголосила що вона допомагає створювати нову організацію, спонсоровану Linux Foundation, яку назвали Open API Initiative. Різні компанії, включно з Google, IBM та Microsoft стали членами-засновниками.[4][5] SmartBear пожертвувала специфікацію Swagger новоствореній групі. Група також розглядала стандарти RAML та API Blueprint Архівовано 22 лютого 2018 у Wayback Machine..[6][7]

1 січня 2016, специфікацію Swagger (англ. Swagger specification) перейменували на специфікацію OpenAPI (англ. OpenAPI Specification), і перемістили її розробку до нового репозиторію на GitHub Архівовано 20 грудня 2016 у Wayback Machine..

SmartBear продовжує розробляти інструменти під брендом Swagger що підтримують OpenAPI специфікацію. В 2016, SmartBear отримав за розробку Swagger нагороду API Award в категорії API Infrastructure.[8]

В 2017, OpenAPI випустила версію 3.0 своєї специфікації.[9] MuleSoft, головний розробник альтернативної RESTful API Modeling Language (RAML), приєднався до OAS і відкрив код свого інструменту API Modeling Framework, який може генерувати OAS-документи з RAML.[10]

Використання[ред. | ред. код]

Додатки що розробляються з допомогою файлів що описують інтерфейси OpenAPI можуть автоматично генерувати документацію методів, параметрів та моделей. Це допомагає синхронізувати документацію, бібліотеки для розробки клієнтів та код застосунку.[11]

Особливості[ред. | ред. код]

Специфікація OpenAPI не залежить від мови. Також її можна поширювати на нові технології і не тільки HTTP протоколи.

З декларативною специфікацією ресурсу OpenAPI, клієнти можуть розуміти і використовувати сервіси без знання деталей реалізації сервера.

Приклад[ред. | ред. код]

Нижче подано приклад OpenAPI специфікації яка описує API з ендпоінтом http://myapi.mydomain/v1[недоступне посилання], яке має один ресурс /data, на який воно може відповідати рядком тексту або JSON-ом з помилкою:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: My API
servers:
  - url: http://myapi.mydomain/v1
paths:
  /data:
    get:
      summary: Get data
      responses:
        '201':
          description: Data response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Data"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Data:
      type: string

Інструменти для роботи з OpenAPI[ред. | ред. код]

Open API Initiative підтримує список реалізацій третьої версії специфікації[12]. Також існують неофіційні списки. [13][14].

SmartBear досі випускає свої інструменти для OpenAPI під брендом Swagger.

Фреймворк Swagger UI дозволяє розробникам та іншим задіяним в проекті спеціалістам взаємодіяти з API в графічному інтерфейсі "пісочниця", який дає поняття про те як API відповідає на запити з різними параметрами.

Swagger-Codegen містить двигун на основі шаблонів, який генерує документацію, код клієнтів API та заглушки серверів різними мовами програмування згідно специфікації OpenAPI.

Див. також[ред. | ред. код]

Зноски[ред. | ред. код]

  1. Linux Foundation wants to extend Swagger in connected buildings | Business Cloud News. Архів оригіналу за 20 липня 2018. Процитовано 22 квітня 2016. 
  2. Governance - OpenAPI Initiative. OpenAPI Initiative. Архів оригіналу за 20 вересня 2016. Процитовано 23 квітня 2020. 
  3. SmartBear Assumes Sponsorship of Swagger API Open Source Project. SmartBear. Архів оригіналу за 24 жовтня 2016. Процитовано 25 березня 2015. 
  4. SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger. ProgrammableWeb. 10 листопада 2015. Архів оригіналу за 9 листопада 2016. Процитовано 21 квітня 2016. 
  5. New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services. www.linuxfoundation.org. Архів оригіналу за 27 квітня 2016. Процитовано 22 квітня 2016. 
  6. Montcheuil, Yves de. In 2016, the need for an API meta-language will crystallize. InfoWorld. Архів оригіналу за 10 серпня 2016. Процитовано 25 квітня 2016. 
  7. Amazon API Gateway Now Supports Swagger Definition Import. InfoQ. Архів оригіналу за 29 вересня 2017. Процитовано 25 квітня 2016. 
  8. API World 2016. Архів оригіналу за 3 листопада 2016. Процитовано 22 лютого 2018. 
  9. The OpenAPI Spec, Based on Swagger, Reaches 3.0. InfoQ. Архів оригіналу за 23 лютого 2018. Процитовано 14 травня 2017. 
  10. The HTTP API space is Consolidating around OAS. InfoQ. Архів оригіналу за 23 лютого 2018. Процитовано 14 травня 2017. 
  11. swagger-api/swagger-spec. GitHub. Процитовано 1 грудня 2015. 
  12. OAI/OpenAPI-Specification. GitHub. Архів оригіналу за 26 червня 2020. Процитовано 23 квітня 2020. 
  13. APIs-guru/awesome-openapi3. GitHub. Процитовано 23 квітня 2020. 
  14. OpenAPI.Tools. Архів оригіналу за 10 травня 2020. Процитовано 23 квітня 2020. 

Посилання[ред. | ред. код]