Специфікація OpenAPI, початково відома як Swagger - це специфікація машиночитабельних файлів з інтерфейсами, для опису, створення, використання і візуалізації REST веб сервісів. Існують різноманітні інструменти що можуть генерувати код, документацію і тести за файлом з описом інтерфейсу. За розробкою специфікації OpenAPI (OAS) наглядає Open API Initiative, проект Linux Foundation. Історія Розробка Swagger почалась в 2010. В березні 2015, SmartBear Software купила Swagger API specification у Reverb Technologies. В листопаді 2015, SmartBear, компанія яка підтримувала специфікацію Swagger та пов'язані інструменти, оголосила що вона допомагає створювати нову організацію, спонсоровану Linux Foundation, яку назвали Open API Initiative. Різні компанії, включно з Google, IBM та Microsoft стали членами-засновниками. SmartBear пожертвувала специфікацію Swagger новоствореній групі. Група також розглядала стандарти RAML та API Blueprint .
1 січня 2016, специфікацію Swagger () перейменували на специфікацію OpenAPI (), і перемістили її розробку до нового репозиторію на GitHub .
SmartBear продовжує розробляти інструменти під брендом Swagger що підтримують OpenAPI специфікацію. В 2016, SmartBear отримав за розробку Swagger нагороду API Award в категорії API Infrastructure.
В 2017, OpenAPI випустила версію 3.0 своєї специфікації. MuleSoft, головний розробник альтернативної RESTful API Modeling Language (RAML), приєднався до OAS і відкрив код свого інструменту API Modeling Framework, який може генерувати OAS-документи з RAML.
Використання Додатки що розробляються з допомогою файлів що описують інтерфейси OpenAPI можуть автоматично генерувати документацію методів, параметрів та моделей. Це допомагає синхронізувати документацію, бібліотеки для розробки клієнтів та код застосунку.
Особливості Специфікація 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 підтримує список реалізацій третьої версії специфікації. Також існують неофіційні списки. .
SmartBear досі випускає свої інструменти для OpenAPI під брендом Swagger.
Фреймворк Swagger UI дозволяє розробникам та іншим задіяним в проекті спеціалістам взаємодіяти з API в графічному інтерфейсі "пісочниця", який дає поняття про те як API відповідає на запити з різними параметрами.
Swagger-Codegen містить двигун на основі шаблонів, який генерує документацію, код клієнтів API та заглушки серверів різними мовами програмування згідно специфікації OpenAPI.
Див. також Representational State Transfer
Зноски
Посилання Open API Initiative (OAI) Swagger OpenAPI Specification на Github Directory of OpenAPI definitions Онлайн редактор специфікації OpenAPI