Инструмент создания и документирования кода покоя

Я рассматриваю инструмент документации для создания бэкэнд для веб-службы, который будет использоваться в нескольких клиентах вместе с OAuth и возможностью множественных ревизий. Я уже знал о пасеке, но, проведя небольшое исследование, я нашел другие значительно более выгодные решения с прибыльным promises.

RAML, по-видимому, является перспективным хорошим генерированием кода и возможностью повторного использования. Но он, похоже, не способен создавать макет сервера. И я не могу понять, почему apiblueprint нельзя использовать для создания клиентских библиотек и скелетов на стороне сервера для REST API.

Лучшим вариантом использования для нас будет документация api, клиентской библиотеки iOS/Android/wp/js для использования этой услуги, которая может быть автоматически сгенерирована вместе с приложением node express/restify, которое предоставляет скелет для записи кода, Наряду с проверками api и нагрузками.

Какое решение из RAML/Swagger/Apiary подходит для этого?

Ответ 1

Пожалуйста, ознакомьтесь с Swagger Codegen (бесплатно, с открытым исходным кодом), который может генерировать как серверные заглушки, так и клиенты API на разных языках.

Многие компании/проекты используют его в производстве: https://github.com/swagger-api/swagger-codegen#companiesprojects-using-swagger-codegen

Поддерживаемые langauges/frameworks:

клиенты API: ActionScript, Bash, С# (.net 2.0, 4.0 или новее), С++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Go, Groovy, haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign), Node.js(ES5, ES6, AngularJS с аннотациями компилятора Google Closure) Objective-C, Perl, PHP, Python, Ruby, Scala, Swift (2.x, 3.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)

Опусты сервера: С# (ASP.NET Core, NancyFx), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy), PHP (Lumen, Slim, Silex, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)

Генераторы документации API: HTML, Confluence Wiki

Отказ от ответственности: я являюсь ведущим участником проекта с открытым исходным кодом.

Ответ 2

Отказ от ответственности: я работаю для Apiary

Я не думаю, что это хорошая идея.

Ваша потребность в макетных серверах намекает на то, что вы приняли путь к описанию-до-реализации, что хорошо.

Однако идея состоит в том, что, развиваясь против mock-сервера, вы выполняете итерацию по дизайну API (это одна из причин, почему имеет смысл делать это в текстовых инструментах вместо кода)... и это твердая часть.

Есть несколько новых инструментов, поддерживающих строительные леса, но реальная проблема заключается в том, как обновить подставное приложение после обновления плана. Я знаю, что некоторые люди занимаются этим, но они еще не выпущены.

На мой взгляд, лучший подход заключается в разработке реального прототипа против издевающегося API для тестирования UX полученного приложения. Как только дизайн будет достаточно стабильным, вы начнете разрабатывать другие клиенты, а также сервер, в конечном итоге расширяя оригинальный дизайн.

Вы тестируете их с соответствующими инструментами, найденными на соответствующих языках, поскольку они лучше всего подходят для данного варианта использования. Чтобы проверить, что реализация соответствует проекту (ака письменного контракта), вы можете использовать dredd.

Любой инструмент, который взаимодействует поверх этого, должен принимать план в качестве ввода вместо того, чтобы генерировать библиотеку, которая может быть расширена вручную, что невозможно поддерживать.

Ответ 3

RAML предоставляет интегрированную бесплатную размещенную службу, которую вы можете развернуть одним щелчком мыши в API Designer. После того, как вы включили mocking, попробуйте - он будет немедленно включен в интегрированную консоль API, и вы сможете дополнительно использовать свой издеваемый API, используя baseURI, вставленный в ваш RAML файл.

Кроме того, в ближайшем будущем мы будем открывать дополнительные серверные рамки (у нас уже есть инфраструктура Mule и JAX-RS) (включая Node). Поколение клиентов немного дальше, но также довольно скоро (сначала javascript, затем другие).

Раскрытие информации: Я активно участвую в инициативе RAML и работаю в MuleSoft в качестве менеджера продуктов для многих инструментов RAML, которые мы разрабатываем.

Ответ 4

Если консоль RAML не достаточно легка, вы можете найти https://github.com/kevinrenskers/raml2html действительно полезную и удобную для начала.

Он не содержит всех функций, которые делает консоль RAML (например, Try out, для тестирования API оттуда), но по-прежнему является отличным инструментом для документации.