OpenAPI
![](http://upload.wikimedia.org/wikipedia/commons/thumb/0/05/WikipediaOpenAPI.png/300px-WikipediaOpenAPI.png)
Специфікація 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.
Див. також
- Representational State Transfer
Зноски
- ↑ Linux Foundation wants to extend Swagger in connected buildings | Business Cloud News. Архів оригіналу за 20 липня 2018. Процитовано 22 квітня 2016.
- ↑ Governance - OpenAPI Initiative. OpenAPI Initiative. Архів оригіналу за 20 вересня 2016. Процитовано 23 квітня 2020.
- ↑ SmartBear Assumes Sponsorship of Swagger API Open Source Project. SmartBear. Архів оригіналу за 24 жовтня 2016. Процитовано 25 березня 2015.
- ↑ SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger. ProgrammableWeb. 10 листопада 2015. Архів оригіналу за 9 листопада 2016. Процитовано 21 квітня 2016.
- ↑ New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services. www.linuxfoundation.org. Архів оригіналу за 27 квітня 2016. Процитовано 22 квітня 2016.
- ↑ Montcheuil, Yves de. In 2016, the need for an API meta-language will crystallize. InfoWorld. Архів оригіналу за 10 серпня 2016. Процитовано 25 квітня 2016.
- ↑ Amazon API Gateway Now Supports Swagger Definition Import. InfoQ. Архів оригіналу за 29 вересня 2017. Процитовано 25 квітня 2016.
- ↑ API World 2016. Архів оригіналу за 3 листопада 2016. Процитовано 22 лютого 2018.
- ↑ The OpenAPI Spec, Based on Swagger, Reaches 3.0. InfoQ. Архів оригіналу за 23 лютого 2018. Процитовано 14 травня 2017.
- ↑ The HTTP API space is Consolidating around OAS. InfoQ. Архів оригіналу за 23 лютого 2018. Процитовано 14 травня 2017.
- ↑ swagger-api/swagger-spec. GitHub. Процитовано 1 грудня 2015.
- ↑ OAI/OpenAPI-Specification. GitHub. Архів оригіналу за 26 червня 2020. Процитовано 23 квітня 2020.
- ↑ APIs-guru/awesome-openapi3. GitHub. Процитовано 23 квітня 2020.
- ↑ OpenAPI.Tools. Архів оригіналу за 10 травня 2020. Процитовано 23 квітня 2020.
Посилання
- Open API Initiative (OAI) [Архівовано 22 жовтня 2016 у Wayback Machine.]
- Swagger [Архівовано 8 листопада 2016 у Wayback Machine.]
- OpenAPI Specification [Архівовано 20 грудня 2016 у Wayback Machine.] на Github
- Directory of OpenAPI definitions [Архівовано 26 грудня 2017 у Wayback Machine.]
- Онлайн редактор специфікації OpenAPI [Архівовано 6 червня 2018 у Wayback Machine.]