apidoc

Описание проекта

apidoc — система документации для API, поддерживающая визуальное редактирование, симуляцию ответов, динамическое предварительное просмотра и отладку, а также экспорт в PDF.

Описание функций

• Визуальное редактирование: поддерживает редактирование интерфейсов API через форму, без необходимости ручного редактирования swagger.json
• Симуляция ответов: поддерживает динамическое генерирование симуляции ответов с помощью JavaScript, что позволяет разрабатывать frontend и backend независимо (без использования аннотаций типа @Controller, @ApiOperation и т.д.)
• Поддержка тестовых случаев: поддерживает тестовые случаи для простых интерфейсов API, используя JSON для конфигурации параметров запроса и JavaScript для проверки результатов с помощью assert и expect
• Динамическое предварительное просмотра и отладка: после редактирования интерфейса API страница предварительного просмотра обновляется в реальном времени, что позволяет непосредственно отлаживать вызовы при включенной симуляции
• Экспорт в PDF: на странице предварительного просмотра есть меню "Оффлайн документация MD", с помощью плагина writage можно вручную экспортировать документацию в PDF (с закладками)
• Локальная отладка: совместно с nginx можно отлаживать локальные интерфейсы API, импортировать локальный swagger и сгенерировать документацию для интерфейсов##### Способ использования

1. Создание базы данных: apidoc (с использованием кодировки utf8mb4 или utf8), импорт скрипта: api-web/db/sosoapi-1. 0. 0. sql
2. Изменение конфигурации: файлы filter-dev-master. properties и mail-cfg. properties в проекте api-web
3. Сборка проекта: mvn install, mvn compile resources:resources war:exploded -f api-web/pom. xml
4. Развертывание на tomcat: <Context docBase="apidoc/api-web/target/apidoc" path="/apidoc" reloadable="true"/>
5. Доступ: http://localhost:8080/apidoc/, вход: admin@qq. com, пароль: 123456, [apidoc](https://api. xlongwei. com/apidoc/)
6. Развертывание в продакшн: sh deploy. sh, mvn compile resources:resources war:exploded -P env-aliyun-master -f api-web/pom. xml

Оптимизированные возможности

1. Порядок приоритета интерфейсных протоколов: интерфейс Inter > документ ApiDoc > URL, при симуляции игнорируются уже существующие схемы, хосты и basePath в ApiDoc
2. Поддержка симуляции интерфейсов: можно указать ответы для параметров запроса, а также динамически генерировать ответы с помощью JavaScript, [демонстрация](https://api. xlongwei. com/apidoc/pass/apidoc/demo. htm? doc=1), [симуляция](https://api. xlongwei. com/apidoc/pass/apidoc/demo. htm? doc=1&mock=true), при неудачной симуляции возвращается структура схемы ответа и комментарии
3. Поддержка генерации файла group. json для knife4j-front, [демонстрация](https://api. xlongwei. com/swagger/doc. html? doc=1), [симуляция](https://api. xlongwei. com/swagger/doc. html? doc=1&mock=true)
4. Установка плагина writage позволяет сохранять в PDF-документ, подробности в [документации](https://api. xlongwei. com/doku. php? id=tools:swagger), пример: knife4j-front/sosoapi_demo. pdf 5.Логи перенаправлены в logback, поддержка вывода логов на logserver.
5. Поддержка тестовых случаев: можно добавлять несколько тестовых случаев для интерфейсов, поддержка массового выполнения тестовых случаев и переключения режима симуляции.

Онлайн-демонстрация

Демонстрационные ссылки: 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.

• Оптимизация мобильных страниц: Фронтенд-страницы плохо отображаются на мобильных устройствах. После поворота экрана страницы становятся более удобными для использования.

Контакты для сотрудничества

• QQ-группа: 957806743, DingTalk-группа: 21975907
• Электронная почта: admin@xlongwei.com