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.[6][7]

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

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. Процитовано 2016-04-22. 
  2. Governance - OpenAPI Initiative. OpenAPI Initiative. Процитовано 23 квітня 2020. 
  3. SmartBear Assumes Sponsorship of Swagger API Open Source Project. SmartBear. Процитовано 2015-03-25. 
  4. SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger. ProgrammableWeb. 2015-11-10. Процитовано 2016-04-21. 
  5. New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services. www.linuxfoundation.org. Архів оригіналу за 2016-04-27. Процитовано 2016-04-22. 
  6. Montcheuil, Yves de. In 2016, the need for an API meta-language will crystallize. InfoWorld. Процитовано 2016-04-25. 
  7. Amazon API Gateway Now Supports Swagger Definition Import. InfoQ. Процитовано 2016-04-25. 
  8. API World 2016
  9. The OpenAPI Spec, Based on Swagger, Reaches 3.0. InfoQ. Процитовано 2017-05-14. 
  10. The HTTP API space is Consolidating around OAS. InfoQ. Процитовано 2017-05-14. 
  11. swagger-api/swagger-spec. GitHub. Процитовано 2015-12-01. 
  12. OAI/OpenAPI-Specification. GitHub. Процитовано 23 квітня 2020. 
  13. APIs-guru/awesome-openapi3. GitHub. Процитовано 23 квітня 2020. 
  14. OpenAPI.Tools. Процитовано 23 квітня 2020. 

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