Π’Π°ΠΊ всС-Ρ‚Π°ΠΊΠΈ RAML ΠΈΠ»ΠΈ OAS (Swagger)?

Π’ Π΄ΠΈΠ½Π°ΠΌΠΈΡ‡Π½ΠΎΠΌ ΠΌΠΈΡ€Π΅ микросСрвисов ΠΈΠ·ΠΌΠ΅Π½ΠΈΡ‚ΡŒΡΡ ΠΌΠΎΠΆΠ΅Ρ‚ всС Ρ‡Ρ‚ΠΎ ΡƒΠ³ΠΎΠ΄Π½ΠΎ β€” любой ΠΊΠΎΠΌΠΏΠΎΠ½Π΅Π½Ρ‚ ΠΌΠΎΠΆΠ½ΠΎ ΠΏΠ΅Ρ€Π΅ΠΏΠΈΡΠ°Ρ‚ΡŒ Π½Π° Π΄Ρ€ΡƒΠ³ΠΎΠΌ языкС, ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΡƒΡ ΠΈΠ½Ρ‹Π΅ Ρ„Ρ€Π΅ΠΉΠΌΠ²ΠΎΡ€ΠΊΠΈ ΠΈ Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρƒ. НСизмСнными Π΄ΠΎΠ»ΠΆΠ½Ρ‹ ΠΎΡΡ‚Π°Π²Π°Ρ‚ΡŒΡΡ лишь ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Ρ‹, для Ρ‚ΠΎΠ³ΠΎ, Ρ‡Ρ‚ΠΎΠ±Ρ‹ с микросСрвисом ΠΌΠΎΠΆΠ½ΠΎ Π±Ρ‹Π»ΠΎ Π²Π·Π°ΠΈΠΌΠΎΠ΄Π΅ΠΉΡΡ‚Π²ΠΎΠ²Π°Ρ‚ΡŒ ΠΈΠ·Π²Π½Π΅ Π½Π° Π½Π΅ΠΊΠΎΠΉ постоянной основС, Π²Π½Π΅ зависимости ΠΎΡ‚ Π²Π½ΡƒΡ‚Ρ€Π΅Π½Π½ΠΈΡ… ΠΌΠ΅Ρ‚Π°ΠΌΠΎΡ€Ρ„ΠΎΠ·. И сСгодня ΠΌΡ‹ расскаТСм ΠΎ нашСй ΠΏΡ€ΠΎΠ±Π»Π΅ΠΌΠ΅ Π²Ρ‹Π±ΠΎΡ€Π° Ρ„ΠΎΡ€ΠΌΠ°Ρ‚Π° описания ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ² ΠΈ подСлимся Π½Π°ΠΉΠ΄Π΅Π½Π½Ρ‹ΠΌΠΈ Π°Ρ€Ρ‚Π΅Ρ„Π°ΠΊΡ‚Π°ΠΌΠΈ.

Π’Π°ΠΊ всС-Ρ‚Π°ΠΊΠΈ RAML ΠΈΠ»ΠΈ OAS (Swagger)?

ΠŸΠΎΡΡ‚ ΠΏΠΎΠ΄Π³ΠΎΡ‚ΠΎΠ²ΠΈΠ»ΠΈ Анна ΠœΠ΅Π»Π΅Ρ…ΠΎΠ²Π° ΠΈ Π’Π»Π°Π΄ΠΈΠΌΠΈΡ€ Π›Π°ΠΏΠ°Ρ‚ΠΈΠ½

ΠœΠΈΠΊΡ€ΠΎΡΠ΅Ρ€Π²ΠΈΡΡ‹. ΠŸΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ Acronis Cyber Cloud ΠΌΡ‹ поняли, Ρ‡Ρ‚ΠΎ Π½Π°ΠΌ Π½ΠΈΠΊΡƒΠ΄Π° ΠΎΡ‚ Π½ΠΈΡ… Π½Π΅ Π΄Π΅Ρ‚ΡŒΡΡ. А ΠΏΡ€ΠΎΠ΅ΠΊΡ‚ΠΈΡ€ΠΎΠ²Π°Π½ΠΈΠ΅ микросСрвиса Π½Π΅Π²ΠΎΠ·ΠΌΠΎΠΆΠ½ΠΎ Π±Π΅Π· Ρ„ΠΎΡ€ΠΌΠ°Π»ΠΈΠ·Π°Ρ†ΠΈΠΈ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Π°, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ прСдставляСт собой интСрфСйс микросСрвиса.

Но ΠΊΠΎΠ³Π΄Π° Π² ΠΏΡ€ΠΎΠ΄ΡƒΠΊΡ‚Π΅ содСрТится большС Ρ‡Π΅ΠΌ ΠΎΠ΄ΠΈΠ½ ΠΊΠΎΠΌΠΏΠΎΠ½Π΅Π½Ρ‚, ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ° ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Π° становится рСгулярной Π°ΠΊΡ‚ΠΈΠ²Π½ΠΎΡΡ‚ΡŒΡŽ, нСвольно Π½Π°Ρ‡ΠΈΠ½Π°Π΅ΡˆΡŒ Π·Π°Π΄ΡƒΠΌΡ‹Π²Π°Ρ‚ΡŒΡΡ ΠΎΠ± ΠΎΠΏΡ‚ΠΈΠΌΠΈΠ·Π°Ρ†ΠΈΠΈ процСсса. Бтановится ΠΎΡ‡Π΅Π²ΠΈΠ΄Π½Ρ‹ΠΌ, Ρ‡Ρ‚ΠΎ интСрфСйс (ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚) ΠΈ имплСмСнтация (микросСрвис) Π΄ΠΎΠ»ΠΆΠ½Ρ‹ Π΄Ρ€ΡƒΠ³ Π΄Ρ€ΡƒΠ³Ρƒ ΡΠΎΠΎΡ‚Π²Π΅Ρ‚ΡΡ‚Π²ΠΎΠ²Π°Ρ‚ΡŒ, Ρ‡Ρ‚ΠΎ Ρ€Π°Π·Π½Ρ‹Π΅ ΠΊΠΎΠΌΠΏΠΎΠ½Π΅Π½Ρ‚Ρ‹ Π΄ΠΎΠ»ΠΆΠ½Ρ‹ Π΄Π΅Π»Π°Ρ‚ΡŒ ΠΎΠ΄Π½ΠΈ ΠΈ Ρ‚Π΅ ΠΆΠ΅ Π²Π΅Ρ‰ΠΈ ΠΎΠ΄ΠΈΠ½Π°ΠΊΠΎΠ²ΠΎ, ΠΈ Ρ‡Ρ‚ΠΎ Π±Π΅Π· Ρ†Π΅Π½Ρ‚Ρ€Π°Π»ΠΈΠ·ΠΎΠ²Π°Π½Π½ΠΎΠ³ΠΎ принятия всСх этих Ρ€Π΅ΡˆΠ΅Π½ΠΈΠΉ каТдая ΠΊΠΎΠΌΠ°Π½Π΄Π° Π±ΡƒΠ΄Π΅Ρ‚ Π²Ρ‹Π½ΡƒΠΆΠ΄Π΅Π½Π° снова ΠΈ снова Ρ‚Ρ€Π°Ρ‚ΠΈΡ‚ΡŒ врСмя Π½Π° ΠΈΡ… ΠΏΠΎΠ»ΡƒΡ‡Π΅Π½ΠΈΠ΅.

Π’Π°ΠΊ всС-Ρ‚Π°ΠΊΠΈ RAML ΠΈΠ»ΠΈ OAS (Swagger)?
Π‘Ρ…Π΅ΠΌΠ° мкросСрвисов Amazon ΠΈΠ· Ρ‚Π²ΠΈΡ‚Π° Π’Π΅Ρ€Π½Π΅Ρ€Π° ВогСлиса, Π‘TO Amazon
Π’ Ρ‡Π΅ΠΌ ΠΆΠ΅ состоит Π΄ΠΈΠ»Π΅ΠΌΠΌΠ°? Π”Π΅ Ρ„Π°ΠΊΡ‚ΠΎ Π΅ΡΡ‚ΡŒ Π΄Π²Π° способа взаимодСйствия микросСрвисов – HTTP Rest ΠΈ gRPC ΠΎΡ‚ ΠΊΠΎΠΌΠΏΠ°Π½ΠΈΠΈ Google. НС ТСлая Π±Ρ‹Ρ‚ΡŒ Π²ΠΎΠ²Π»Π΅Ρ‡Π΅Π½Π½Ρ‹ΠΌΠΈ Π² стСк Ρ‚Π΅Ρ…Π½ΠΎΠ»ΠΎΠ³ΠΈΠΉ Google, ΠΌΡ‹ Π²Ρ‹Π±Ρ€Π°Π»ΠΈ HTTP Rest. Аннотации ΠΊ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Π°ΠΌ HTTP REST Ρ‡Π°Ρ‰Π΅ всСго ΠΎΠΏΠΈΡΡ‹Π²Π°ΡŽΡ‚ΡΡ ΠΎΠ΄Π½ΠΈΠΌ ΠΈΠ· Π΄Π²ΡƒΡ… Ρ„ΠΎΡ€ΠΌΠ°Ρ‚ΠΎΠ²: RAML ΠΈ OAS, Ρ€Π°Π½Π΅Π΅ извСстный ΠΊΠ°ΠΊ Swagger ΠŸΠΎΡΡ‚ΠΎΠΌΡƒ каТдая ΠΊΠΎΠΌΠ°Π½Π΄Π° Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊΠΎΠ² сталкиваСтся с Π½Π΅ΠΎΠ±Ρ…ΠΎΠ΄ΠΈΠΌΠΎΡΡ‚ΡŒΡŽ ΡΠ΄Π΅Π»Π°Ρ‚ΡŒ Π²Ρ‹Π±ΠΎΡ€ Π² ΠΏΠΎΠ»ΡŒΠ·Ρƒ ΠΎΠ΄Π½ΠΎΠ³ΠΎ ΠΈΠ· стандартов. Но, ΠΊΠ°ΠΊ Π²Ρ‹ΡΡΠ½ΠΈΠ»ΠΎΡΡŒ, ΡΠ΄Π΅Π»Π°Ρ‚ΡŒ этот Π²Ρ‹Π±ΠΎΡ€ ΠΌΠΎΠΆΠ΅Ρ‚ Π±Ρ‹Ρ‚ΡŒ ΠΎΡ‡Π΅Π½ΡŒ нСпросто.

Π—Π°Ρ‡Π΅ΠΌ Π½ΡƒΠΆΠ½Ρ‹ Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΈ?

Аннотация Π½ΡƒΠΆΠ½Π° для Ρ‚ΠΎΠ³ΠΎ, Ρ‡Ρ‚ΠΎΠ±Ρ‹ внСшний ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚Π΅Π»ΡŒ ΠΌΠΎΠ³ Π»Π΅Π³ΠΊΠΎ Ρ€Π°Π·ΠΎΠ±Ρ€Π°Ρ‚ΡŒΡΡ, Ρ‡Ρ‚ΠΎ ΠΌΠΎΠΆΠ½ΠΎ Π΄Π΅Π»Π°Ρ‚ΡŒ с вашим сСрвисом Ρ‡Π΅Ρ€Π΅Π· Π΅Π³ΠΎ HTTP-интСрфСйс. Π’ΠΎ Π΅ΡΡ‚ΡŒ Π½Π° Π±Π°Π·ΠΎΠ²ΠΎΠΌ ΡƒΡ€ΠΎΠ²Π½Π΅ аннотация Π΄ΠΎΠ»ΠΆΠ½Π° ΡΠΎΠ΄Π΅Ρ€ΠΆΠ°Ρ‚ΡŒ ΠΊΠ°ΠΊ ΠΌΠΈΠ½ΠΈΠΌΡƒΠΌ список доступных рСсурсов, ΠΈΡ… HTTP-ΠΌΠ΅Ρ‚ΠΎΠ΄ΠΎΠ², Ρ‚Π΅Π»Π° запросов, пСрСчислСниС ΠΏΠ°Ρ€Π°ΠΌΠ΅Ρ‚Ρ€ΠΎΠ², ΡƒΠΊΠ°Π·Π°Π½ΠΈΠ΅ Π½Π΅ΠΎΠ±Ρ…ΠΎΠ΄ΠΈΠΌΡ‹Ρ… ΠΈ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΈΠ²Π°Π΅ΠΌΡ‹Ρ… Π·Π°Π³ΠΎΠ»ΠΎΠ²ΠΊΠΎΠ², Π° Ρ‚Π°ΠΊΠΆΠ΅ ΠΊΠΎΠ΄ΠΎΠ² Π²ΠΎΠ·Π²Ρ€Π°Ρ‚Π° ΠΈ Ρ„ΠΎΡ€ΠΌΠ°Ρ‚ΠΎΠ² ΠΎΡ‚Π²Π΅Ρ‚ΠΎΠ². ΠšΡ€Π°ΠΉΠ½Π΅ Π²Π°ΠΆΠ½Ρ‹ΠΌ элСмСнтом Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΈ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Π° являСтся ΠΈ ΠΈΡ… словСсноС описаниС(β€œΡ‡Ρ‚ΠΎ Π±ΡƒΠ΄Π΅Ρ‚, Ссли Π΄ΠΎΠ±Π°Π²ΠΈΡ‚ΡŒ этот query-ΠΏΠ°Ρ€Π°ΠΌΠ΅Ρ‚Ρ€ ΠΊ запросу?”, β€œΠ² ΠΊΠ°ΠΊΠΎΠΌ случаС вСрнСтся ΠΊΠΎΠ΄ 400?”)

Π’Π΅ΠΌ Π½Π΅ ΠΌΠ΅Π½Π΅Π΅, ΠΊΠΎΠ³Π΄Π° Ρ€Π΅Ρ‡ΡŒ ΠΈΠ΄Π΅Ρ‚ ΠΎ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ большого количСства микросСрвисов, хочСтся ΠΈΠ·Π²Π»Π΅ΠΊΠ°Ρ‚ΡŒ Π΄ΠΎΠΏΠΎΠ»Π½ΠΈΡ‚Π΅Π»ΡŒΠ½ΡƒΡŽ ΠΏΠΎΠ»ΡŒΠ·Ρƒ ΠΈΠ· написанных Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΉ. НапримСр, Π½Π° основС RAML/Swagger ΠΌΠΎΠΆΠ½ΠΎ Π³Π΅Π½Π΅Ρ€ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ ΠΈ клиСнтский, ΠΈ сСрвСрный ΠΊΠΎΠ΄ Π½Π° ΠΎΠ³Ρ€ΠΎΠΌΠ½ΠΎΠΌ количСствС языков программирования. А Π΅Ρ‰Π΅ ΠΌΠΎΠΆΠ½ΠΎ автоматичСски ΠΏΠΎΠ»ΡƒΡ‡Π°Ρ‚ΡŒ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚Π°Ρ†ΠΈΡŽ ΠΊ микросСрвису ΠΈ Π·Π°Π»ΠΈΠ²Π°Ρ‚ΡŒ Π΅Π΅ Π½Π° ваш developer-portal :).

Π’Π°ΠΊ всС-Ρ‚Π°ΠΊΠΈ RAML ΠΈΠ»ΠΈ OAS (Swagger)?
ΠŸΡ€ΠΈΠΌΠ΅Ρ€ структурированного описания ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚Π°

Π Π΅ΠΆΠ΅ встрСчаСтся ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠ° тСстирования микросСрвисов Π½Π° Π±Π°Π·Π΅ описаний ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ². Если Π²Ρ‹ написали ΠΈ Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΡŽ, ΠΈ ΠΊΠΎΠΌΠΏΠΎΠ½Π΅Π½Ρ‚, Ρ‚ΠΎ ΠΌΠΎΠΆΠ½ΠΎ ΡΠΎΠ·Π΄Π°Ρ‚ΡŒ автотСст, ΠΏΡ€ΠΎΠ²Π΅Ρ€ΡΡŽΡ‰ΠΈΠΉ Π°Π΄Π΅ΠΊΠ²Π°Ρ‚Π½ΠΎΡΡ‚ΡŒ Ρ€Π°Π±ΠΎΡ‚Ρ‹ сСрвиса с Ρ€Π°Π·Π»ΠΈΡ‡Π½Ρ‹ΠΌΠΈ Ρ‚ΠΈΠΏΠ°ΠΌΠΈ Π΄Π°Π½Π½Ρ‹Ρ… Π½Π° Π²Ρ…ΠΎΠ΄Π΅. НС Π²ΠΎΠ·Π²Ρ€Π°Ρ‰Π°Π΅Ρ‚ Π»ΠΈ сСрвис ΠΊΠΎΠ΄ ΠΎΡ‚Π²Π΅Ρ‚Π°, Π½Π΅ описанный Π² Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΈ? Π‘ΠΌΠΎΠΆΠ΅Ρ‚ Π»ΠΈ ΠΊΠΎΡ€Ρ€Π΅ΠΊΡ‚Π½ΠΎ ΠΎΠ±Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ Π·Π°Π²Π΅Π΄ΠΎΠΌΠΎ Π½Π΅Π²Π΅Ρ€Π½Ρ‹Π΅ Π΄Π°Π½Π½Ρ‹Π΅?

Π‘ΠΎΠ»Π΅Π΅ Ρ‚ΠΎΠ³ΠΎ, качСствСнная рСализация Π½Π΅ Ρ‚ΠΎΠ»ΡŒΠΊΠΎ самих ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ², Π½ΠΎ Ρ‚Π°ΠΊΠΆΠ΅ инструмСнтария для Π²ΠΈΠ·ΡƒΠ°Π»ΠΈΠ·Π°Ρ†ΠΈΠΈ Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΉ позволяСт ΡƒΠΏΡ€ΠΎΡΡ‚ΠΈΡ‚ΡŒ Ρ€Π°Π±ΠΎΡ‚Ρƒ с микросСрвисом. Π’ΠΎ Π΅ΡΡ‚ΡŒ Ссли Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΠΎΡ€ качСствСнно описал ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚, Π½Π° Π΅Π³ΠΎ основании Π΄ΠΈΠ·Π°ΠΉΠ½Π΅Ρ€Ρ‹ ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊΠΈ Π±ΡƒΠ΄ΡƒΡ‚ Π²Π½Π΅Π΄Ρ€ΡΡ‚ΡŒ сСрвис Π² Π΄Ρ€ΡƒΠ³ΠΈΠ΅ ΠΏΡ€ΠΎΠ΄ΡƒΠΊΡ‚Ρ‹ Π±Π΅Π· Π΄ΠΎΠΏΠΎΠ»Π½ΠΈΡ‚Π΅Π»ΡŒΠ½Ρ‹Ρ… Π²Ρ€Π΅ΠΌΠ΅Π½Π½Ρ‹Ρ… Π·Π°Ρ‚Ρ€Π°Ρ‚.

Для Ρ€Π°Π±ΠΎΡ‚Ρ‹ Π΄ΠΎΠΏΠΎΠ»Π½ΠΈΡ‚Π΅Π»ΡŒΠ½Ρ‹Ρ… инструмСнтов ΠΈ RAML, ΠΈ OAS ΠΈΠΌΠ΅ΡŽΡ‚ Π²ΠΎΠ·ΠΌΠΎΠΆΠ½ΠΎΡΡ‚ΡŒ добавлСния ΠΌΠ΅Ρ‚Π°Π΄Π°Π½Π½Ρ‹Ρ…, Π½Π΅ прСдусмотрСнных стандартом (Π½Π°ΠΏΡ€ΠΈΠΌΠ΅Ρ€, Ρ‚Π°ΠΊ это дСлаСтся Π² OAS).

Π’ ΠΎΠ±Ρ‰Π΅ΠΌ, ΠΏΠΎΠ»Π΅ для творчСства Π² ΠΏΡ€ΠΈΠΌΠ΅Π½Π΅Π½ΠΈΠΈ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ² для микросСрвисов β€” огромноС… ΠΏΠΎ ΠΊΡ€Π°ΠΉΠ½Π΅ΠΉ ΠΌΠ΅Ρ€Π΅ тСорСтичСски

Π‘Ρ€Π°Π²Π½Π΅Π½ΠΈΠ΅ Π΅ΠΆΠ° с ΡƒΠΆΠΎΠΌ

Π’ настоящСС врСмя ΠΏΡ€ΠΈΠΎΡ€ΠΈΡ‚Π΅Ρ‚Π½ΠΎΠ΅ Π½Π°ΠΏΡ€Π°Π²Π»Π΅Π½ΠΈΠ΅ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠΈ Π² Acronis – Ρ€Π°Π·Π²ΠΈΡ‚ΠΈΠ΅ Acronis Cyber Platform. Acronis Cyber Platform – это Π½ΠΎΠ²Ρ‹Π΅ Ρ‚ΠΎΡ‡ΠΊΠΈ ΠΈΠ½Ρ‚Π΅Π³Ρ€Π°Ρ†ΠΈΠΈ сторонних сСрвисов с Acronis Cyber Cloud ΠΈ агСнтской Ρ‡Π°ΡΡ‚ΡŒΡŽ. Π₯отя наши Π²Π½ΡƒΡ‚Ρ€Π΅Π½Π½ΠΈΠ΅ API, описанныС Π² RAML, нас устраивали, Π½Π΅ΠΎΠ±Ρ…ΠΎΠ΄ΠΈΠΌΠΎΡΡ‚ΡŒ ΠΏΡƒΠ±Π»ΠΈΠΊΠ°Ρ†ΠΈΠΈ API ΠΎΠΏΡΡ‚ΡŒ подняло вопрос Π²Ρ‹Π±ΠΎΡ€Π°: ΠΊΠ°ΠΊΠΎΠΉ ΠΆΠ΅ стандарт Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΉ Π»ΡƒΡ‡ΡˆΠ΅ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒ для нашСй Ρ€Π°Π±ΠΎΡ‚Ρ‹?

Π˜Π·Π½Π°Ρ‡Π°Π»ΡŒΠ½ΠΎ казалось, Ρ‡Ρ‚ΠΎ Ρ€Π΅ΡˆΠ΅Π½ΠΈΠΉ Π΄Π²Π° β€” это Π½Π°ΠΈΠ±ΠΎΠ»Π΅Π΅ распространСнныС Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠΈ RAML ΠΈ Swagger (ΠΈΠ»ΠΈ OAS). Но ΠΏΠΎ Ρ„Π°ΠΊΡ‚Ρƒ оказалось, Ρ‡Ρ‚ΠΎ Π°Π»ΡŒΡ‚Π΅Ρ€Π½Π°Ρ‚ΠΈΠ² ΠΊΠ°ΠΊ ΠΌΠΈΠ½ΠΈΠΌΡƒΠΌ Π½Π΅ 2, Π° 3 ΠΈΠ»ΠΈ большС.

Π‘ ΠΎΠ΄Π½ΠΎΠΉ стороны Π΅ΡΡ‚ΡŒ RAML – ΠΌΠΎΡ‰Π½Ρ‹ΠΉ ΠΈ эффСктивный язык. Π’ Π½Π΅ΠΌ Ρ…ΠΎΡ€ΠΎΡˆΠΎ Ρ€Π΅Π°Π»ΠΈΠ·ΠΎΠ²Π°Π½Π° иСрархия ΠΈ наслСдованиС, Ρ‚Π°ΠΊ Ρ‡Ρ‚ΠΎ этот Ρ„ΠΎΡ€ΠΌΠ°Ρ‚ большС ΠΏΠΎΠ΄Ρ…ΠΎΠ΄ΠΈΡ‚ для Π±ΠΎΠ»ΡŒΡˆΠΈΡ… ΠΊΠΎΠΌΠΏΠ°Π½ΠΈΠΉ, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΌ Π½ΡƒΠΆΠ½ΠΎ ΠΌΠ½ΠΎΠ³ΠΎ описаний β€” Ρ‚ΠΎ Π΅ΡΡ‚ΡŒ Π½Π΅ ΠΎΠ΄ΠΈΠ½ ΠΏΡ€ΠΎΠ΄ΡƒΠΊΡ‚, Π° ΠΌΠ½ΠΎΠ³ΠΎ микросСрвисов, Ρƒ ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Ρ… Π΅ΡΡ‚ΡŒ ΠΎΠ±Ρ‰ΠΈΠ΅ части ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ² β€” схСмы Π°ΡƒΡ‚Π΅Π½Ρ„ΠΈΠΊΠ°Ρ†ΠΈΠΈ, ΠΎΠ΄ΠΈΠ½Π°ΠΊΠΎΠ²Ρ‹Π΅ Ρ‚ΠΈΠΏΡ‹ Π΄Π°Π½Π½Ρ‹Ρ…, Ρ‚Π΅Π»Π° ошибок.

Но Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊ RAML, компания Mulesoft, ΠΏΡ€ΠΈΡΠΎΠ΅Π΄ΠΈΠ½ΠΈΠ»Π°ΡΡŒ ΠΊ консорциуму Open API, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ занимаСтся Ρ€Π°Π·Π²ΠΈΡ‚ΠΈΠ΅ΠΌ Swagger. ΠŸΠΎΡΡ‚ΠΎΠΌΡƒ RAML приостановил своС Ρ€Π°Π·Π²ΠΈΡ‚ΠΈΠ΅. Π§Ρ‚ΠΎΠ±Ρ‹ Π²ΠΎΠΎΠ±Ρ€Π°Π·ΠΈΡ‚ΡŒ Ρ„ΠΎΡ€ΠΌΠ°Ρ‚ события ΠΏΡ€Π΅Π΄ΡΡ‚Π°Π²ΡŒΡ‚Π΅, Ρ‡Ρ‚ΠΎ ΠΌΠ΅ΠΉΠ½Ρ‚Π΅ΠΉΠ½Π΅Ρ€Ρ‹ основных ΠΊΠΎΠΌΠΏΠΎΠ½Π΅Π½Ρ‚ΠΎΠ² Linux ΡƒΡˆΠ»ΠΈ Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ Π² Microsoft. Вакая ситуация создаСт прСдпосылки для Ρ‚ΠΎΠ³ΠΎ, Ρ‡Ρ‚ΠΎΠ±Ρ‹ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒ Swagger, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ Π΄ΠΈΠ½Π°ΠΌΠΈΡ‡Π½ΠΎ развиваСтся ΠΈ Π² послСднСй β€” Ρ‚Ρ€Π΅Ρ‚ΡŒΠ΅ΠΉ вСрсии β€” практичСски догоняСт RAML ΠΏΠΎ гибкости ΠΈ Ρ„ΡƒΠ½ΠΊΡ†ΠΈΠΎΠ½Π°Π»ΡŒΠ½ΠΎΡΡ‚ΠΈ.

Если Π±Ρ‹ Π½Π΅ ΠΎΠ΄Π½ΠΎ но…

Как оказалось, Π΄Π°Π»Π΅ΠΊΠΎ Π½Π΅ всС open-source ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Ρ‹ обновились Π΄ΠΎ вСрсии OAS 3.0. Для микросСрвисов Π½Π° Go самым ΠΊΡ€ΠΈΡ‚ΠΈΡ‡Π½Ρ‹ΠΌ Π±ΡƒΠ΄Π΅Ρ‚ отсутствиС Π°Π΄Π°ΠΏΡ‚Π°Ρ†ΠΈΠΈ go-swagger ΠΏΠΎΠ΄ ΡΠ²Π΅ΠΆΡƒΡŽ Π²Π΅Ρ€ΡΠΈΡŽ стандарта. Однако Ρ€Π°Π·Π½ΠΈΡ†Π° ΠΌΠ΅ΠΆΠ΄Ρƒ Swagger 2 ΠΈ Swagger 3 β€” ΠΎΠ³Ρ€ΠΎΠΌΠ½Π°. НапримСр, Π² Ρ‚Ρ€Π΅Ρ‚ΡŒΠ΅ΠΉ вСрсии Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊΠΈ:

  • ΡƒΠ»ΡƒΡ‡ΡˆΠΈΠ»ΠΈ описаниС схСм Π°ΡƒΡ‚Π΅Π½Ρ‚ΠΈΡ„ΠΈΠΊΠ°Ρ†ΠΈΠΈ
  • Π΄ΠΎΠ΄Π΅Π»Π°Π»ΠΈ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΊΡƒ JSON Schema
  • ΠΏΡ€ΠΎΠΊΠ°Ρ‡Π°Π»ΠΈ Π²ΠΎΠ·ΠΌΠΎΠΆΠ½ΠΎΡΡ‚ΡŒ добавлСния ΠΏΡ€ΠΈΠΌΠ΅Ρ€ΠΎΠ²

Битуация получаСтся забавная: ΠΏΡ€ΠΈ Π²Ρ‹Π±ΠΎΡ€Π΅ стандарта Π½ΡƒΠΆΠ½ΠΎ Ρ€Π°ΡΡΠΌΠ°Ρ‚Ρ€ΠΈΠ²Π°Ρ‚ΡŒ RAML, Swagger 2 ΠΈ Swagger 3 ΠΊΠ°ΠΊ ΠΎΡ‚Π΄Π΅Π»ΡŒΠ½Ρ‹Π΅ Π°Π»ΡŒΡ‚Π΅Ρ€Π½Π°Ρ‚ΠΈΠ²Ρ‹. ΠŸΡ€ΠΈ этом Ρ‚ΠΎΠ»ΡŒΠΊΠΎ Swagger 2 ΠΈΠΌΠ΅Π΅Ρ‚ Ρ…ΠΎΡ€ΠΎΡˆΡƒΡŽ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΊΡƒ инструмСнтария OpenSource. RAML – ΠΎΡ‡Π΅Π½ΡŒ гибкий… ΠΈ слоТный, Π° Swagger 3 слабо ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΈΠ²Π°ΡŽΡ‚ΡΡ ΠΊΠΎΠΌΠΌΡŒΡŽΠ½ΠΈΡ‚ΠΈ, Ρ‚Π°ΠΊ Ρ‡Ρ‚ΠΎ Π²Π°ΠΌ придСтся ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒΡΡ инструмСнтами собствСнной Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠΈ ΠΈΠ»ΠΈ коммСрчСскими Ρ€Π΅ΡˆΠ΅Π½ΠΈΡΠΌΠΈ, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅, ΠΊΠ°ΠΊ ΠΏΡ€Π°Π²ΠΈΠ»ΠΎ, стоят вСсьма Π΄ΠΎΡ€ΠΎΠ³ΠΎ.

ΠŸΡ€ΠΈ этом Ссли Π² Swagger сущСствуСт ΠΌΠ½ΠΎΠ³ΠΎ приятных возмоТностСй, Ρ‚Π°ΠΊΠΈΡ… ΠΊΠ°ΠΊ Π³ΠΎΡ‚ΠΎΠ²Ρ‹ΠΉ ΠΏΠΎΡ€Ρ‚Π°Π» editor.swagger.io, Π½Π° ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ ΠΌΠΎΠΆΠ½ΠΎ Π·Π°Π³Ρ€ΡƒΠ·ΠΈΡ‚ΡŒ Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΡŽ ΠΈ ΠΏΠΎΠ»ΡƒΡ‡ΠΈΡ‚ΡŒ Π΅Π΅ Π²ΠΈΠ·ΡƒΠ°Π»ΠΈΠ·Π°Ρ†ΠΈΡŽ с ΠΏΠΎΠ΄Ρ€ΠΎΠ±Π½Ρ‹ΠΌ описаниСм, ссылками ΠΈ связями, Ρ‚ΠΎ для Π±ΠΎΠ»Π΅Π΅ Ρ„ΡƒΠ½Π΄Π°ΠΌΠ΅Π½Ρ‚Π°Π»ΡŒΠ½ΠΎΠ³ΠΎ ΠΈ ΠΌΠ΅Π½Π΅Π΅ Π΄Ρ€ΡƒΠΆΠ΅Π»ΡŽΠ±Π½ΠΎΠ³ΠΎ RAML Ρ‚Π°ΠΊΠΎΠΉ возмоТности Π½Π΅Ρ‚. Π”Π°, ΠΌΠΎΠΆΠ½ΠΎ ΠΏΠΎΠΈΡΠΊΠ°Ρ‚ΡŒ Ρ‡Ρ‚ΠΎ-Ρ‚ΠΎ срСди ΠΏΡ€ΠΎΠ΅ΠΊΡ‚ΠΎΠ² Π½Π° GitHub, Π½Π°ΠΉΡ‚ΠΈ Ρ‚Π°ΠΌ Π°Π½Π°Π»ΠΎΠ³ ΠΈ ΡΠ°ΠΌΠΎΡΡ‚ΠΎΡΡ‚Π΅Π»ΡŒΠ½ΠΎ Π΅Π³ΠΎ Ρ€Π°Π·Π²Π΅Ρ€Π½ΡƒΡ‚ΡŒ. Однако Π² любом случаС ΠΊΡ‚ΠΎ-Ρ‚ΠΎ Π΄ΠΎΠ»ΠΆΠ΅Π½ Π±ΡƒΠ΄Π΅Ρ‚ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΈΠ²Π°Ρ‚ΡŒ ΠΏΠΎΡ€Ρ‚Π°Π», Ρ‡Ρ‚ΠΎ Π½Π΅ Ρ‚Π°ΠΊ ΡƒΠ΄ΠΎΠ±Π½ΠΎ для Π±Π°Π·ΠΎΠ²ΠΎΠ³ΠΎ использования ΠΈΠ»ΠΈ тСстовых Π½ΡƒΠΆΠ΄. ΠšΡ€ΠΎΠΌΠ΅ Ρ‚ΠΎΠ³ΠΎ, swagger Π±ΠΎΠ»Π΅Π΅ β€œΠ±Π΅ΡΠΏΡ€ΠΈΠ½Ρ†ΠΈΠΏΠ΅Π½β€, Π½Ρƒ ΠΈΠ»ΠΈ Π»ΠΈΠ±Π΅Ρ€Π°Π»Π΅Π½ β€” Π΅Π³ΠΎ ΠΌΠΎΠΆΠ½ΠΎ Π³Π΅Π½Π΅Ρ€ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ ΠΈΠ· ΠΊΠΎΠΌΠΌΠ΅Π½Ρ‚Π°Ρ€ΠΈΠ΅Π² Π² ΠΊΠΎΠ΄Π΅, Ρ‡Ρ‚ΠΎ, ΠΊΠΎΠ½Π΅Ρ‡Π½ΠΎ, ΠΈΠ΄Π΅Ρ‚ Π²Ρ€Π°Π·Ρ€Π΅Π· с ΠΏΡ€ΠΈΠ½Ρ†ΠΈΠΏΠΎΠΌ API first ΠΈ Π½Π΅ поддСрТиваСтся Π½ΠΈ ΠΎΠ΄Π½ΠΎΠΉ ΠΈΠ· ΡƒΡ‚ΠΈΠ»ΠΈΡ‚ RAML,

ΠœΡ‹ Π² своС врСмя Π½Π°Ρ‡Π°Π»ΠΈ Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ с RAML, ΠΊΠ°ΠΊ с Π±ΠΎΠ»Π΅Π΅ Π³ΠΈΠ±ΠΊΠΈΠΌ языком, ΠΈ Π² ΠΈΡ‚ΠΎΠ³Π΅ ΠΌΠ½ΠΎΠ³ΠΎ Π΄ΠΎΠ»ΠΆΠ½Ρ‹ Π±Ρ‹Π»ΠΈ Π΄Π΅Π»Π°Ρ‚ΡŒ своими Ρ€ΡƒΠΊΠ°ΠΌΠΈ. НапримСр, Π² ΠΎΠ΄Π½ΠΎΠΌ ΠΈΠ· ΠΏΡ€ΠΎΠ΅ΠΊΡ‚ΠΎΠ² ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΡƒΠ΅Ρ‚ΡΡ ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Π° ramlfications Π² ΡŽΠ½ΠΈΡ‚-тСстах, которая ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΈΠ²Π°Π΅Ρ‚ Ρ‚ΠΎΠ»ΡŒΠΊΠΎ RAML 0.8. Π’Π°ΠΊ Ρ‡Ρ‚ΠΎ ΠΏΡ€ΠΈΡˆΠ»ΠΎΡΡŒ Π΄ΠΎΠ±Π°Π²Π»ΡΡ‚ΡŒ костыли, Ρ‡Ρ‚ΠΎΠ±Ρ‹ ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Π° смогла β€œΠΊΡƒΡˆΠ°Ρ‚ΡŒβ€ RAML вСрсии 1.0.

А Π½ΡƒΠΆΠ½ΠΎ Π»ΠΈ Π²Ρ‹Π±ΠΈΡ€Π°Ρ‚ΡŒ?

Нашаманившись с дописываниСм экосистСмы Ρ€Π΅ΡˆΠ΅Π½ΠΈΠΉ ΠΏΠΎΠ΄ RAML, ΠΌΡ‹ ΠΏΡ€ΠΈΡˆΠ»ΠΈ ΠΊ Ρ‚ΠΎΠΌΡƒ, Ρ‡Ρ‚ΠΎ Π½Π°ΠΌ Π½ΡƒΠΆΠ½ΠΎ ΠΊΠΎΠ½Π²Π΅Ρ€Ρ‚ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ RAML Π² Swagger 2 ΠΈ ΡƒΠΆΠ΅ Π² Π½Π΅ΠΌ ΠΏΡ€ΠΎΠ²ΠΎΠ΄ΠΈΡ‚ΡŒ всю Π°Π²Ρ‚ΠΎΠΌΠ°Ρ‚ΠΈΠ·Π°Ρ†ΠΈΡŽ, ΠΏΡ€ΠΎΠ²Π΅Ρ€ΠΊΡƒ, тСстированиС ΠΈ ΠΏΠΎΡΠ»Π΅Π΄ΡƒΡŽΡ‰ΡƒΡŽ ΠΎΠΏΡ‚ΠΈΠΌΠΈΠ·Π°Ρ†ΠΈΡŽ. Π­Ρ‚ΠΎ Ρ…ΠΎΡ€ΠΎΡˆΠΈΠΉ способ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒ ΠΎΠ΄Π½ΠΎΠ²Ρ€Π΅ΠΌΠ΅Π½Π½ΠΎ ΠΈ Π³ΠΈΠ±ΠΊΠΎΡΡ‚ΡŒ RAML, ΠΈ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΊΡƒ инструмСнтария сообщСства ΠΎΡ‚ Swagger.

Для Ρ€Π΅ΡˆΠ΅Π½ΠΈΡ этой Π·Π°Π΄Π°Ρ‡ΠΈ сущСствуСт Π΄Π²Π° инструмСнта OpenSource, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅ Π΄ΠΎΠ»ΠΆΠ½Ρ‹ ΠΎΠ±Π΅ΡΠΏΠ΅Ρ‡ΠΈΠ²Π°Ρ‚ΡŒ ΠΊΠΎΠ½Π²Π΅Ρ€Ρ‚Π°Ρ†ΠΈΡŽ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ²:

  1. oas-raml-converter – Π½Ρ‹Π½Π΅ нСподдСрТиваСмая ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Π°. Π’ процСссС Ρ€Π°Π±ΠΎΡ‚Ρ‹ с Π½Π΅ΠΉ ΠΌΡ‹ ΠΎΠ±Π½Π°Ρ€ΡƒΠΆΠΈΠ»ΠΈ, Ρ‡Ρ‚ΠΎ Ρƒ Π½Π΅Π΅ Π²ΠΎΠ·Π½ΠΈΠΊΠ°Π΅Ρ‚ ряд ΠΏΡ€ΠΎΠ±Π»Π΅ΠΌ со слоТными RAML’ами, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅ β€œΡ€Π°Π·ΠΌΠ°Π·Π°Π½Ρ‹β€ ΠΏΠΎ Π±ΠΎΠ»ΡŒΡˆΠΎΠΌΡƒ количСству Ρ„Π°ΠΉΠ»ΠΎΠ². Π­Ρ‚Π° ΠΏΡ€ΠΎΠ³Ρ€Π°ΠΌΠΌΠ° написана Π½Π° JavaScript ΠΈ выполняСт рСкурсивный ΠΎΠ±Ρ…ΠΎΠ΄ синтаксичСского Π΄Π΅Ρ€Π΅Π²Π°. Из-Π·Π° динамичСской Ρ‚ΠΈΠΏΠΈΠ·Π°Ρ†ΠΈΠΈ Ρ€Π°Π·ΠΎΠ±Ρ€Π°Ρ‚ΡŒΡΡ Π² этом ΠΊΠΎΠ΄Π΅ становится слоТно, Ρ‚Π°ΠΊ Ρ‡Ρ‚ΠΎ ΠΌΡ‹ Ρ€Π΅ΡˆΠΈΠ»ΠΈ Π½Π΅ Ρ‚Ρ€Π°Ρ‚ΠΈΡ‚ΡŒ врСмя Π½Π° написаниС ΠΏΠ°Ρ‚Ρ‡Π΅ΠΉ ΠΊ ΡƒΠΌΠΈΡ€Π°ΡŽΡ‰Π΅ΠΉ ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Π΅.
  2. webapi-parser β€” инструмСнт ΠΎΡ‚ Ρ‚ΠΎΠΉ ΠΆΠ΅ ΠΊΠΎΠΌΠΏΠ°Π½ΠΈΠΈ, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ ΠΏΡ€Π΅Ρ‚Π΅Π½Π΄ΡƒΠ΅Ρ‚ Π½Π° Π³ΠΎΡ‚ΠΎΠ²Π½ΠΎΡΡ‚ΡŒ ΠΊΠΎΠ½Π²Π΅Ρ€Ρ‚ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ всС ΠΈ вся, ΠΏΡ€ΠΈΡ‡Π΅ΠΌ Π² Π»ΡŽΠ±ΡƒΡŽ сторону. На сСгодняшний дСнь заявлСна ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΊΠ° RAML 0.8, RAML 1.0 ΠΈ Swagger 2.0. Однако Π½Π° ΠΌΠΎΠΌΠ΅Π½Ρ‚ нашСго исслСдования ΡƒΡ‚ΠΈΠ»ΠΈΡ‚Π° Π±Ρ‹Π»Π° Π΅Ρ‰Π΅ ΠšΠ ΠΠ™ΠΠ• сырой ΠΈ Π½Π΅ΠΏΡ€ΠΈΠ³ΠΎΠ΄Π½ΠΎΠΉ для использования. Π Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊΠΈ ΡΠΎΠ·Π΄Π°ΡŽΡ‚ своСго Ρ€ΠΎΠ΄Π° IR, Ρ‡Ρ‚ΠΎ ΠΏΠΎΠ·Π²ΠΎΠ»ΠΈΡ‚ ΠΈΠΌ Π² Π±ΡƒΠ΄ΡƒΡ‰Π΅ΠΌ быстро Π΄ΠΎΠ±Π°Π²Π»ΡΡ‚ΡŒ Π½ΠΎΠ²Ρ‹Π΅ стандарты. Но ΠΏΠΎΠΊΠ° всС это просто Π½Π΅ Ρ€Π°Π±ΠΎΡ‚Π°Π΅Ρ‚.

И это Π΅Ρ‰Π΅ Π½Π΅ всС слоТности, с ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΌΠΈ ΠΌΡ‹ ΡΡ‚ΠΎΠ»ΠΊΠ½ΡƒΠ»ΠΈΡΡŒ. Одним ΠΈΠ· шагов нашСго ΠΏΠ°ΠΉΠΏΠ»Π°ΠΉΠ½Π° являСтся ΠΏΡ€ΠΎΠ²Π΅Ρ€ΠΊΠ° Ρ‚ΠΎΠ³ΠΎ, Ρ‡Ρ‚ΠΎ RAML ΠΈΠ· рСпозитория являСтся ΠΊΠΎΡ€Ρ€Π΅ΠΊΡ‚Π½Ρ‹ΠΌ ΠΎΡ‚Π½ΠΎΡΠΈΡ‚Π΅Π»ΡŒΠ½ΠΎ спСцификации. ΠœΡ‹ ΠΏΠ΅Ρ€Π΅ΠΏΡ€ΠΎΠ±ΠΎΠ²Π°Π»ΠΈ нСсколько ΡƒΡ‚ΠΈΠ»ΠΈΡ‚. Π£Π΄ΠΈΠ²ΠΈΡ‚Π΅Π»ΡŒΠ½ΠΎ, Π½ΠΎ всС ΠΎΠ½ΠΈ Ρ€ΡƒΠ³Π°Π»ΠΈΡΡŒ Π½Π° наши Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΈ Π² Ρ€Π°Π·Π½Ρ‹Ρ… мСстах ΠΈ ΡΠΎΠ²Π΅Ρ€ΡˆΠ΅Π½Π½ΠΎ Ρ€Π°Π·Π½Ρ‹ΠΌΠΈ Π΄ΡƒΡ€Π½Ρ‹ΠΌΠΈ словами. ΠŸΡ€ΠΈΡ‡Π΅ΠΌ Π½Π΅ всСгда ΠΏΠΎ Π΄Π΅Π»Ρƒ :).

Π’ ΠΊΠΎΠ½Ρ†Π΅ ΠΊΠΎΠ½Ρ†ΠΎΠ² ΠΌΡ‹ ΠΎΡΡ‚Π°Π½ΠΎΠ²ΠΈΠ»ΠΈΡΡŒ Π½Π° Π½Ρ‹Π½Π΅ ΡƒΡΡ‚Π°Ρ€Π΅Π²ΡˆΠ΅ΠΌ ΠΏΡ€ΠΎΠ΅ΠΊΡ‚Π΅, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹ΠΉ Ρ‚Π°ΠΊΠΆΠ΅ ΠΈΠΌΠ΅Π΅Ρ‚ ряд ΠΏΡ€ΠΎΠ±Π»Π΅ΠΌ (ΠΈΠ½ΠΎΠ³Π΄Π° ΠΏΠ°Π΄Π°Π΅Ρ‚ Π½Π° Ρ€ΠΎΠ²Π½ΠΎΠΌ мСстС, ΠΈΠΌΠ΅Π΅Ρ‚ ΠΏΡ€ΠΎΠ±Π»Π΅ΠΌΡ‹ ΠΏΡ€ΠΈ Ρ€Π°Π±ΠΎΡ‚Π΅ с рСгулярными выраТСниями). Π’Π°ΠΊΠΈΠΌ ΠΎΠ±Ρ€Π°Π·ΠΎΠΌ, ΠΌΡ‹ Π½Π΅ нашли способа Ρ€Π΅ΡˆΠΈΡ‚ΡŒ Π·Π°Π΄Π°Ρ‡ΠΈ Π²Π°Π»ΠΈΠ΄Π°Ρ†ΠΈΠΈ ΠΈ ΠΊΠΎΠ½Π²Π΅Ρ€Ρ‚Π°Ρ†ΠΈΠΈ Π½Π° Π±Π°Π·Π΅ бСсплатных инструмСнтов, ΠΈ Ρ€Π΅ΡˆΠΈΠ»ΠΈ ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒΡΡ коммСрчСской ΡƒΡ‚ΠΈΠ»ΠΈΡ‚ΠΎΠΉ. Π’ Π±ΡƒΠ΄ΡƒΡ‰Π΅ΠΌ, ΠΊΠΎΠ³Π΄Π° OpenSource срСдства станут Π±ΠΎΠ»Π΅Π΅ Ρ€Π°Π·Π²ΠΈΡ‚Ρ‹ΠΌΠΈ, Ρ€Π΅ΡˆΠ΅Π½ΠΈΠ΅ этой Π·Π°Π΄Π°Ρ‡ΠΈ, Π²ΠΎΠ·ΠΌΠΎΠΆΠ½ΠΎ, станСт ΠΏΡ€ΠΎΡ‰Π΅. А ΠΏΠΎΠΊΠ° Ρ‚Ρ€ΡƒΠ΄ΠΎ-Π²Ρ€Π΅ΠΌΠ΅Π½Π½Ρ‹Π΅ Π·Π°Ρ‚Ρ€Π°Ρ‚Ρ‹ Π½Π° β€œΠ΄ΠΎΠΏΠΈΠ»ΠΈΠ²Π°Π½ΠΈΠ΅β€ показались Π½Π°ΠΌ Π±ΠΎΠ»Π΅Π΅ Π·Π½Π°Ρ‡ΠΈΡ‚Π΅Π»ΡŒΠ½Ρ‹ΠΌΠΈ, Ρ‡Π΅ΠΌ ΡΡ‚ΠΎΠΈΠΌΠΎΡΡ‚ΡŒ коммСрчСского сСрвиса.

Π—Π°ΠΊΠ»ΡŽΡ‡Π΅Π½ΠΈΠ΅

ПослС всСго этого Π½Π°ΠΌ Π·Π°Ρ…ΠΎΡ‚Π΅Π»ΠΎΡΡŒ ΠΏΠΎΠ΄Π΅Π»ΠΈΡ‚ΡŒΡΡ ΠΎΠΏΡ‹Ρ‚ΠΎΠΌ ΠΈ ΠΎΡ‚ΠΌΠ΅Ρ‚ΠΈΡ‚ΡŒ, Ρ‡Ρ‚ΠΎ ΠΏΠ΅Ρ€Π΅Π΄ Π²Ρ‹Π±ΠΎΡ€ΠΎΠΌ инструмСнта для описания ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ² Π½ΡƒΠΆΠ½ΠΎ Ρ‡Π΅Ρ‚ΠΊΠΎ ΠΎΠΏΡ€Π΅Π΄Π΅Π»ΠΈΡ‚ΡŒΡΡ, Ρ‡Π΅Π³ΠΎ Π²Ρ‹ ΠΎΡ‚ Π½Π΅Π³ΠΎ Ρ…ΠΎΡ‚ΠΈΡ‚Π΅, ΠΈ ΠΊΠ°ΠΊΠΎΠΉ Π±ΡŽΠ΄ΠΆΠ΅Ρ‚ Π³ΠΎΡ‚ΠΎΠ²Ρ‹ Π²Π»ΠΎΠΆΠΈΡ‚ΡŒ. Если Π·Π°Π±Ρ‹Ρ‚ΡŒ ΠΏΡ€ΠΎ OpenSource, ΡƒΠΆΠ΅ сСйчас Π΅ΡΡ‚ΡŒ большоС количСство сСрвисов ΠΈ ΠΏΡ€ΠΎΠ΄ΡƒΠΊΡ‚ΠΎΠ², ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅ ΠΏΠΎΠΌΠΎΠ³ΡƒΡ‚ ΡΠ΄Π΅Π»Π°Ρ‚ΡŒ ΠΏΡ€ΠΎΠ²Π΅Ρ€ΠΊΡƒ, ΡΠΊΠΎΠ½Π²Π΅Ρ€Ρ‚ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ, провСсти Π²Π°Π»ΠΈΠ΄Π°Ρ†ΠΈΡŽ. Но ΠΎΠ½ΠΈ стоят Π΄ΠΎΡ€ΠΎΠ³ΠΎ, Π° ΠΈΠ½ΠΎΠ³Π΄Π° β€” ΠΎΡ‡Π΅Π½ΡŒ Π΄ΠΎΡ€ΠΎΠ³ΠΎ. Для большой ΠΊΠΎΠΌΠΏΠ°Π½ΠΈΠΈ Ρ‚Π°ΠΊΠΈΠ΅ Π·Π°Ρ‚Ρ€Π°Ρ‚Ρ‹ Ρ‚Π΅Ρ€ΠΏΠΈΠΌΡ‹, Π½ΠΎ для стартапа ΠΌΠΎΠ³ΡƒΡ‚ ΡΡ‚Π°Ρ‚ΡŒ большой Π½Π°Π³Ρ€ΡƒΠ·ΠΊΠΎΠΉ.

ΠžΠΏΡ€Π΅Π΄Π΅Π»ΠΈΡ‚ΡŒ Π½Π°Π±ΠΎΡ€ инструмСнтов, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅ Π²Ρ‹ Π±ΡƒΠ΄Π΅Ρ‚Π΅ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒ ΠΏΠΎΠ·ΠΆΠ΅. НапримСр, Ссли Π²Π°ΠΌ Π½ΡƒΠΆΠ½ΠΎ просто ΠΎΡ‚ΠΎΠ±Ρ€Π°ΠΆΠ°Ρ‚ΡŒ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚, ΠΏΡ€ΠΎΡ‰Π΅ Π±ΡƒΠ΄Π΅Ρ‚ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚ΡŒ Swagger 2, Ρƒ ΠΊΠΎΡ‚ΠΎΡ€ΠΎΠ³ΠΎ Π΅ΡΡ‚ΡŒ красивый API, вСдь Π² RAML Π²Π°ΠΌ придСтся ΠΏΠΎΠ΄Π½ΠΈΠΌΠ°Ρ‚ΡŒ ΠΈ ΠΏΠΎΠ΄Π΄Π΅Ρ€ΠΆΠΈΠ²Π°Ρ‚ΡŒ сСрвис ΡΠ°ΠΌΠΎΡΡ‚ΠΎΡΡ‚Π΅Π»ΡŒΠ½ΠΎ.
Π§Π΅ΠΌ большС Π±ΡƒΠ΄Π΅Ρ‚ Ρƒ вас Π·Π°Π΄Π°Ρ‡, Ρ‚Π΅ΠΌ ΡˆΠΈΡ€Π΅ Π±ΡƒΠ΄Π΅Ρ‚ ΠΏΠΎΡ‚Ρ€Π΅Π±Π½ΠΎΡΡ‚ΡŒ Π² инструмСнтах, Π° ΠΎΠ½ΠΈ Ρ€Π°Π·Π½Ρ‹Π΅ для Ρ€Π°Π·Π½Ρ‹Ρ… ΠΏΠ»Π°Ρ‚Ρ„ΠΎΡ€ΠΌ, ΠΈ Π»ΡƒΡ‡ΡˆΠ΅ сразу ΠΎΠ·Π½Π°ΠΊΠΎΠΌΠΈΡ‚ΡŒΡΡ с доступными вСрсиями, Ρ‡Ρ‚ΠΎΠ±Ρ‹ ΡΠ΄Π΅Π»Π°Ρ‚ΡŒ Π²Ρ‹Π±ΠΎΡ€, ΠΌΠΈΠ½ΠΈΠΌΠΈΠ·ΠΈΡ€ΡƒΡŽΡ‰ΠΈΠΉ ваши Π·Π°Ρ‚Ρ€Π°Ρ‚Ρ‹ Π² Π±ΡƒΠ΄ΡƒΡ‰Π΅ΠΌ.

Но стоит ΠΏΡ€ΠΈΠ·Π½Π°Ρ‚ΡŒ, Ρ‡Ρ‚ΠΎ всС экосистСмы, ΡΡƒΡ‰Π΅ΡΡ‚Π²ΡƒΡŽΡ‰ΠΈΠ΅ Π½Π° сСгодняшний дСнь, Π½Π΅ΡΠΎΠ²Π΅Ρ€ΡˆΠ΅Π½Π½Ρ‹. ΠŸΠΎΡΡ‚ΠΎΠΌΡƒ Ссли Π² ΠΊΠΎΠΌΠΏΠ°Π½ΠΈΠΈ Π΅ΡΡ‚ΡŒ Ρ„Π°Π½Π°Ρ‚Ρ‹, ΠΊΠΎΡ‚ΠΎΡ€Ρ‹Π΅ Π»ΡŽΠ±ΡΡ‚ Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ Π² RAML, ΠΏΠΎΡ‚ΠΎΠΌΡƒ Ρ‡Ρ‚ΠΎ β€œΠΎΠ½ позволяСт Π±ΠΎΠ»Π΅Π΅ Π³ΠΈΠ±ΠΊΠΎ Π²Ρ‹Ρ€Π°ΠΆΠ°Ρ‚ΡŒ мысли”, ΠΈΠ»ΠΈ, Π½Π°ΠΎΠ±ΠΎΡ€ΠΎΡ‚, ΠΏΡ€Π΅Π΄ΠΏΠΎΡ‡ΠΈΡ‚Π°ΡŽΡ‚ Swagger, ΠΏΠΎΡ‚ΠΎΠΌΡƒ Ρ‡Ρ‚ΠΎ β€œΠΎΠ½ понятнСС”, β€” Π»ΡƒΡ‡ΡˆΠ΅ всСго ΠΎΡΡ‚Π°Π²ΠΈΡ‚ΡŒ ΠΈΡ… Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ Π² Ρ‚ΠΎΠΌ, Π² Ρ‡Π΅ΠΌ ΠΎΠ½ΠΈ ΠΏΡ€ΠΈΠ²Ρ‹ΠΊΠ»ΠΈ ΠΈ хотят, ΠΏΠΎΡ‚ΠΎΠΌΡƒ Ρ‡Ρ‚ΠΎ инструмСнтарий любого ΠΈΠ· Ρ„ΠΎΡ€ΠΌΠ°Ρ‚ΠΎΠ² Ρ‚Ρ€Π΅Π±ΡƒΠ΅Ρ‚ Π΄ΠΎΡ€Π°Π±ΠΎΡ‚ΠΊΠΈ напильником.

Π§Ρ‚ΠΎ касаСтся нашСго ΠΎΠΏΡ‹Ρ‚Π°, Π² ΡΠ»Π΅Π΄ΡƒΡŽΡ‰ΠΈΡ… постах ΠΌΡ‹ расскаТСм ΠΎ Ρ‚ΠΎΠΌ, ΠΊΠ°ΠΊΠΈΠ΅ β€” статичСскиС ΠΈ динамичСскиС ΠΏΡ€ΠΎΠ²Π΅Ρ€ΠΊΠΈ ΠΌΡ‹ ΠΏΡ€ΠΎΠ²ΠΎΠ΄ΠΈΠΌ Π½Π° Π±Π°Π·Π΅ нашСй RAML-Swagger Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹, Π° Ρ‚Π°ΠΊΠΆΠ΅ ΠΎ Ρ‚ΠΎΠΌ, ΠΊΠ°ΠΊΡƒΡŽ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚Π°Ρ†ΠΈΡŽ ΠΌΡ‹ Π³Π΅Π½Π΅Ρ€ΠΈΡ€ΡƒΠ΅ΠΌ ΠΈΠ· ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ², ΠΈ ΠΊΠ°ΠΊΠΈΠΌ ΠΎΠ±Ρ€Π°Π·ΠΎΠΌ всС это Ρ€Π°Π±ΠΎΡ‚Π°Π΅Ρ‚.

Волько зарСгистрированныС ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚Π΅Π»ΠΈ ΠΌΠΎΠ³ΡƒΡ‚ ΡƒΡ‡Π°ΡΡ‚Π²ΠΎΠ²Π°Ρ‚ΡŒ Π² опросС. Π’ΠΎΠΉΠ΄ΠΈΡ‚Π΅, поТалуйста.

А ΠΊΠ°ΠΊΠΎΠΉ язык Π²Ρ‹ ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΡƒΠ΅Ρ‚Π΅ для Π°Π½Π½ΠΎΡ‚Π°Ρ†ΠΈΠΉ ΠΊΠΎΠ½Ρ‚Ρ€Π°ΠΊΡ‚ΠΎΠ² микросСрвисов?

  • RAML 0.8

  • RAML 1.0

  • Swagger 2

  • OAS3 (aka )

  • Blueprint

  • Π”Ρ€ΡƒΠ³ΠΎΠΉ

  • НС ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΡƒΡŽ

ΠŸΡ€ΠΎΠ³ΠΎΠ»ΠΎΡΠΎΠ²Π°Π»ΠΈ 100 ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚Π΅Π»Π΅ΠΉ. Π’ΠΎΠ·Π΄Π΅Ρ€ΠΆΠ°Π»ΠΈΡΡŒ 24 ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚Π΅Π»Ρ.

Π˜ΡΡ‚ΠΎΡ‡Π½ΠΈΠΊ: habr.com