Хорошая генерация кода rest и инструмент документации [закрыто]

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

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

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

какое решение из RAML / Swagger / пасеки подходит для этого лучше всего?

4 ответов


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

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

поддерживаемые языки / фреймворки:

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

сервер заглушки: C# (с ASP.NET ядро, NancyFx), Эрланг, иди, Хаскелл, Ява (MSF4J, Весна, прилив-отлив, JAX-РТС: КДИ, CXF, в Инфлектор, RestEasy), РНР (люмен, Тонкий, Двуокись Кремния, Зенд Выразительный), Питон (Колбу), NodeJS, Рубин (Синатра, Rails5), Скала (Финч, Scalatra)

генераторы документации API: HTML, слияние Wiki

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

обновление: в мае 2018 года около 50 ведущих авторов и создателей шаблонов Swagger Codegen решили развить Swagger Codegen, чтобы поддерживать версию под названием Генератор OpenAPI. Пожалуйста, обратитесь к Q & A для получения дополнительной информации.


отказ от ответственности: я работаю на пасеке

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

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

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

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

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

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

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


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

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

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


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

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