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. [Архівовано 2016-05-06 у Wayback Machine.]
  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. [Архівовано 2016-11-09 у Wayback Machine.]
  5. ↑ New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services. www.linuxfoundation.org. Архів оригіналу за 27 квітня 2016. Процитовано 22 квітня 2016. [Архівовано 2016-04-27 у Wayback Machine.]
  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.

Посилання

This article is issued from Вікіпедія. The text is available under Creative Commons Attribution-Share Alike 4.0 unless otherwise noted. Additional terms may apply for the media files.