OpenAPI

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

Специфікація API української вікіпедії, відображена в Swagger UI, з прикладом запиту

Історія

Розробка 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%5Bнедоступне+посилання%5D, яке має один ресурс /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. Процитовано 22 квітня 2016.
  2. Governance - OpenAPI Initiative. OpenAPI Initiative. Процитовано 23 квітня 2020.
  3. SmartBear Assumes Sponsorship of Swagger API Open Source Project. SmartBear. Процитовано 25 березня 2015.
  4. SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger. ProgrammableWeb. 10 листопада 2015. Процитовано 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. Процитовано 25 квітня 2016.
  7. Amazon API Gateway Now Supports Swagger Definition Import. InfoQ. Процитовано 25 квітня 2016.
  8. API World 2016
  9. The OpenAPI Spec, Based on Swagger, Reaches 3.0. InfoQ. Процитовано 14 травня 2017.
  10. The HTTP API space is Consolidating around OAS. InfoQ. Процитовано 14 травня 2017.
  11. swagger-api/swagger-spec. GitHub. Процитовано 1 грудня 2015.
  12. OAI/OpenAPI-Specification. GitHub. Процитовано 23 квітня 2020.
  13. APIs-guru/awesome-openapi3. GitHub. Процитовано 23 квітня 2020.
  14. OpenAPI.Tools. Процитовано 23 квітня 2020.

Посилання
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.