Необходимо создать API-документ для существующего приложения, написанного с помощью nodejs/express

Question

У меня есть несколько частных API, написанных простым старым экспрессом. Время выпустить это и предоставить некоторую документацию API.

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

Я хотел бы предоставить документ как часть подресурса под моим API (т.е. я не хочу запускать другой сервер или поддомен). Возможно '/api/docs'. Плюсом также был бы пользовательский интерфейс, который я мог бы встроить в свое приложение, которое могло бы анализировать документы и, по крайней мере, обеспечивать хорошее представление документов в формате html (взаимодействие с API является плюсом).

Такие вещи, как swagger-node - это круто, но мне нужно было бы переписать весь мой экспресс-код для интеграции swagger. На тот момент у меня большие инвестиции, и я тесно связан с чванством.

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

РЕДАКТИРОВАТЬ:

Я мог бы выдать спецификацию Swagger из рукописного документа. Проблема, которую я вижу в том, что вы должны определить basePath в чванстве док. Это на самом деле не позволяет мне легко развертывать в разных доменах.

Answer 1

Существует широкий спектр инструментов node.js для интеграции Swagger с вашим приложением, и я предполагаю, что они предлагают различные способы сделать это. Вы можете найти список таких интеграций здесь - https://github.com/webron/swagger-spec/ - но я могу вам сказать, что есть дополнительные инструменты, которых там нет в списке. Вы можете попробовать поискать в github swagger и node/express.

Что касается ручной спецификации и basePath - Swagger 2.0 фактически решит это за вас. Вы можете использовать онлайн-редактор - http://editor.swagger.io/ - чтобы написать свои спецификации в более удобной для человека форме YAML, которую затем можно экспортировать в JSON. В отличие от Swagger 1.2 и предыдущих версий, basePath теперь разделен на три свойства: schemes (http, https), host (домен, порт) и basePath (корневой контекст приложения). Ни одно из этих свойств не является обязательным, и все они по умолчанию соответствуют тому, что обслуживает файл swagger.json (сама спецификация). schemes по умолчанию используется схема сервиса swagger.json, host по умолчанию используется хост, используемый для обслуживания swagger.json и basePath будет \ если не указано иное. Я считаю, что это должно решить ваши проблемы относительно basePath.