Swagger, API Blueprint, RAML ... Как сохранить спецификацию API и реализацию в синхронизации?

Я довольно новичок в мире языков описания веб-API и только что начал изучать Swagger, API Blueprint и RAML для наших приложений JAX-RS. Все они выглядят великолепно, но у меня есть один вопрос.Swagger, API Blueprint, RAML ... Как сохранить спецификацию API и реализацию в синхронизации?

Мое понимание в обратном порядке, вы сначала проектируете API, генерируете хорошую документацию HTML, возможно, а также макет, а затем начинаете кодирование.

Но что, если вам придется изменить подпись вашего API, например, изменить модель тела ответа по некоторым причинам во время реализации? Я имею в виду, что в этом случае ваша спецификация API должна быть изменена, и вы должны вручную отредактировать свой API-интерфейс, чтобы синхронизировать его с вашим кодом, поскольку, похоже, нет зрелой библиотеки, которая генерирует API Spec из исходного кода. (Я тестировал такие библиотеки для Swagger и RAML, но не APIB, так как я не мог найти библиотеку конвертирования исходного кода JAX-RS.) В таком случае, как описано выше, как вы справляетесь с этим?

Вы редактируете API Spec вручную или используете некоторую библиотеку, чтобы сделать это автоматически? Если последнее, не могли бы вы сообщить мне имя библиотеки?

источник

2015-04-15 tsz662

FWIW, swagger-core разрабатывается в течение ~ 4 лет, не уверен, почему вы находите не зрелого. – Ron

С помощью подхода «сверху вниз» вы также можете создавать программные артефакты (например, аннотированные интерфейсы JAX-RS и DTO), которые синхронизируют ваш код с вашими спецификациями во время компиляции. Таким образом, спецификация дисков dev в любое время, никаких изменений, инициированных кодом, которые могут непреднамеренно нарушить контракт. –

@Ron, спасибо за ответ и «зрелый» может быть не правильным словом. Что касается Swagger, нам не разрешено использовать аннотации rung runtime, и единственная библиотека Source-to-Swagger, которую я нашел на этом сайте, не смогла воспроизвести всю вещь нашего веб-API в формате Swagger. – tsz662

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

Слоган Дредд является:

Нет более устаревшие API Документация

Дредд является система тестирования API, который потребляет API Blueprint и тестирует против API бэкэндом. Вы можете легко сделать его частью своего набора тестов, чтобы он мог быть частью всего жизненного цикла разработки. От проектирования до локального TDD, непрерывной интеграции и даже проверки после развертывания живых API.

Поэтому я рекомендую отредактировать/составить описание API вручную как часть процесса проектирования, а затем протестировать его вместо генерации документации из кода.

Отказ от ответственности: Я сопровождающим Дредд

источник

2015-04-16 05:58:02 netmilk

благодарит за комментарий. Я знаю Dredd и вскоре попробую его на работе (в настоящее время я пишу образец API с помощью плагина Atom API Blueprint). Я уверен, что Дредд сыграет значительную роль в ситуации, о которой я уже говорил выше. Кстати, почему никто не пишет библиотеку Blueprint от источника к API? (Я знаю, что Restlet Studio планирует реализовать такую функцию.) – tsz662

Для Raml, вы можете посмотреть на abao. Это утилита командной строки, чтобы проверить, соответствует ли спецификация RAML встроенной реализации. Я не использовал его сам, но он кажется эквивалентным Дредду.

источник

2015-10-02 09:56:08 Jan

Спасибо за информацию, но похоже, что мы собираемся адаптировать swagger. Если что-нибудь придумает цепочку инструментов swagger, мы можем изменить наш курс, и в этом случае я обязательно проверю abao. – tsz662

Swagger, API Blueprint, RAML ... Как сохранить спецификацию API и реализацию в синхронизации?

ответ

Смежные вопросы