apidoc
Описание проекта
Система apidoc для создания документов API с поддержкой визуального редактирования, имитации ответов, динамического просмотра и отладки, экспорта PDF и других функций.
Описание функциональности
- Визуальное редактирование: позволяет редактировать интерфейсы через формы, без необходимости ручного изменения swagger.json
- Имитация ответов: поддерживает генерацию имитационных ответов с помощью JavaScript, что обеспечивает разделение фронтенда и бэкендаприложений (без использования аннотаций @Controller, @ApiOperation и т.п.)
- Поддержка тестовых случаев: позволяет создавать тестовые случаи для простых интерфейсов, используя JSON для конфигурации запросов и методы assert, expect для проверки результатов
- Динамическое обновление и отладка: страница предварительного просмотра автоматически обновляется при изменении интерфейса, позволяя непосредственно отлаживать вызовы при активированной имитации
- Экспорт PDF: меню "Оффлайн документ MD" на странице предварительного просмотра позволяет экспортировать документ в PDF с использованием плагина writage (с закладками)
- Локальная отладка: совместимость с nginx позволяет отлаживать локальные интерфейсы, импортировать локальный swagger и генерировать документацию для интерфейсов
Инструкция по использованию
- Создайте базу данных: apidoc (с использованием символьного набора utf8mb4 или utf8), импортируйте скрипт: api-web/db/sosoapi-1.0.0.sql
- Измените конфигурацию: файлы filter-dev-master.properties и mail-cfg.properties в проекте api-web
- Соберите проект: mvn install, mvn compile resources:resources war:exploded -f api-web/pom.xml
- Разверните на tomcat:
<Context docBase="apidoc/api-web/target/apidoc" path="/apidoc" reloadable="true"/>
- Пример доступа: http://localhost:8080/apidoc/, вход: admin@qq.com, пароль: 123456, apidoc
- Онлайн развертывание: sh deploy.sh, mvn compile resources:resources war:exploded -P env-aliyun-master -f api-web/pom.xml
Улучшенные возможности
- Приоритет протокола интерфейса: Интерфейс Inter > Документ ApiDoc > Адрес Url, при имитации игнорируются scheme, host, basePath из существующего ApiDoc
- Поддержка имитации интерфейсов: возможность указывать ответы для параметров запроса или использовать JavaScript для динамической генерации ответов, демонстрация, имитация, при неудачной имитации возвращается структура schema и информация о комментариях
- Поддержка генерации файла group.json для knife4j-front, демонстрация, имитация
- Установка плагина writage позволяет сохранять документы в PDF, подробнее см. документацию, пример: knife4j-front/sosoapi_demo.pdf
- Переход на использование logback для журналирования, поддержка вывода журналов на logserver
- Поддержка тестовых случаев: возможность добавления нескольких тестовых случаев для интерфейсов, поддержка выполнения тестовых случаев пакетами и переключения режима имитации
Онлайн демонстрация
Адреса демонстраций:
apidoc
knife4j
Часто задаваемые вопросы
- Символьный набор базы данных: при наличии высокой версии MySQL рекомендуется использовать utf8mb4, в противном случае можно использовать utf8.
spring-mybatis.xml, подключение к пулу используется druid, так как bonecp ранее выдавал ошибки при работе с более ранними версиями MySQL.
- Невозможность отправки электронной почты:
java.lang.NoSuchMethodError: com.sun.mail.util.TraceInputStream, org.apache.commons.mail.EmailException: Отправка электронной почты на сервере завершилась ошибкой. Решение: base-mail/pom.xml, измените commons-email на версию 1.5.
- Оптимизация мобильной версии сайта:
Фронтэнд-страницы плохо отображаются на мобильных устройствах, но после поворота экрана становятся доступными для взаимодействия.
Контакт для сотрудничества
Комментарии ( 0 )