Когда Сваггер встретил Торну, он мгновенно стал выше!

Swagger — очень популярный инструмент для создания документов API, я думаю, многие его используют! Если вы используете его слишком часто, вы можете почувствовать, что его интерфейс уродлив, а функции слабы. Сегодня я хотел бы порекомендовать инструмент Torna, который можно использовать со Swagger для создания веб-сайта документации API с красивым интерфейсом и мощными функциями, надеюсь, он будет полезен всем!

Адрес фактического проекта электронной коммерции SpringBoot (50k+star):GitHub.com/macro-positive/…

Знакомство с Торной

Torna — это решение для документирования интерфейса корпоративного уровня, которое можно использовать со Swagger. Он имеет следующие функции:

Управление документами: поддержка добавления, удаления, модификации и проверки документов интерфейса, отладки интерфейса, управления словарем, а также функций импорта и экспорта;
Управление разрешениями: он поддерживает управление разрешениями документов интерфейса и одновременно имеет три роли посетителя, разработчика и администратора;
Двойной режим: оригинальный двойной режим,管理模式Может использоваться для редактирования содержимого документа,浏览模式Просто обратитесь к документации, и интерфейс свободен от других элементов.

Торна Проект Архитектура

Torna — проект с разделением интерфейса и бэкенда, бэкенд реализован с помощью SpringBoot+MyBatis, а фронтенд — с помощью Vue+ElementUI, стек технологий очень мейнстримный! Он может не только создать веб-сайт с документацией по API, но и очень хороший обучающий проект.Давайте сначала взглянем на его структуру проекта.

Для начала нам нужно скачать исходный код Torna, адрес загрузки:git ee.com/ все подставь меня...

После успешной загрузки импортируйте код в IDEA, структура проекта следующая:

давайте посмотрим еще разserverСтруктура модуля, очень стандартный проект SpringBoot;

посмотри сноваfrontСтруктура модулей, довольно стандартный проект Vue, который стоит изучить!

Установить

Теперь давайте запустим Torna и испытаем его функции.Существует два метода установки для Windows и Linux.

Windows

Давайте представим метод установки Torna под Windows.Если вы хотите изучить Torna более подробно, вы можете использовать этот метод.

серверная часть работает

Сначала создайте базу данныхtorna, а затем импортируйтеmysql.sqlСкрипт, после успешного импорта структура таблицы выглядит следующим образом;

Измените файл конфигурации проектаserver/boot/src/main/resources/application.properties, изменить соответствующую конфигурацию подключения к базе данных;

# Server port
server.port=7700

# MySQL host
mysql.host=localhost:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root

Затем запустите класс запуска проектаTornaApplicationmain, консоль выводит следующую информацию, чтобы указать, что запуск прошел успешно.

Фронтенд работает

Войдите в каталог внешнего интерфейсаfront,бегатьnpm installкоманда для установки зависимостей;

В это время, если вы столкнетесьnode-sassЕсли его невозможно установить, вы можете установить его напрямую, используя следующую команду;

npm i node-sass --sass_binary_site=https://npm.taobao.org/mirrors/node-sass/

После установки зависимостей можно пройтиnpm run devКоманда для запуска проекта и доступа к адресу после успешного запуска:http://localhost:9530/

Через пароль учетной записи опытаadmin@torna.cn:123456Доступ к сервису Torna возможен, интерфейс по-прежнему хорош!

Linux

Установить Torna под Linux с помощью Docker очень просто, если вы хотите использовать Torna только для служб документации API, вы можете использовать этот метод.

Сначала нам нужно скачать образ Torna Docker;

docker pull tanghc2020/torna:latest

После завершения загрузки файл конфигурацииapplication.propertiesСкопируйте файл конфигурации в/mydata/torna/configкаталог и изменить конфигурацию базы данных;

# Server port
server.port=7700

# MySQL host
mysql.host=192.168.3.101:3306
# Schema name
mysql.schema=torna
# Insure the account can run CREATE/ALTER sql.
mysql.username=root
mysql.password=root

Затем запустите службу Torna с помощью следующей команды;

docker run -p 7700:7700 --name torna \
-v /mydata/torna/config:/torna/config \
-d tanghc2020/torna:latest

Поскольку внешний и внутренний проекты напрямую включены в образ, его можно использовать напрямую, а адрес доступа:http://192.168.3.101:7700

использовать

Torna поддерживает импорт документов интерфейса из различных инструментов, включая Swagger, smart-doc, OpenAPI, Postman и т. д. Теперь давайте испытаем его функции!

Используйте с Swagger

Torna может значительно улучшить функцию Swagger, а интерфейс достаточно красивый, давайте испытаем его ниже!

Прежде чем его использовать, нам нужно его настроить в Torna, для начала настроим открытого пользователя и создадим нового.macroаккаунт, помнитеAppKeyиSecret;

затем создайте проектmall-tiny-trona;

Далее создайте модуль и откройтеOpenAPIэтикетка, получить请求路径иtoken;

После этого интегрировать плагин Torna в проект с помощью Swagger очень просто, достаточно добавить следующие зависимости;

<!-- Torna Swagger 插件 -->
<dependency>
    <groupId>cn.torna</groupId>
    <artifactId>swagger-plugin</artifactId>
    <version>1.2.6</version>
    <scope>test</scope>
</dependency>

затем вresourcesДобавьте файлы конфигурации в каталогtorna.json, описание конфигурации может ссылаться на комментарии;

{
  // 开启推送
  "enable": true,
  // 扫描package，多个用;隔开
  "basePackage": "com.macro.mall.tiny.controller",
  // 推送URL，IP端口对应Torna服务器
  "url": "http://localhost:7700/api",
  // appKey
  "appKey": "20211103905498418195988480",
  // secret
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  // 模块token
  "token": "74365d40038d4f648ae65a077d956836",
  // 调试环境，格式：环境名称,调试路径，多个用"|"隔开
  "debugEnv": "test,http://localhost:8088",
  // 推送人
  "author": "macro",
  // 打开调试:true/false
  "debug": true,
  // 是否替换文档，true：替换，false：不替换（追加）。默认：true
  "isReplace": true
}

Далее по телефонуSwaggerPluginизpushDocметод отправки документации по интерфейсу в Torna;

@RunWith(SpringRunner.class)
@SpringBootTest
public class MallTinyApplicationTests {

    @Test
    public void pushDoc(){
        // 将文档推送到Torna服务中去，默认查找resources下的torna.json
        SwaggerPlugin.pushDoc();
    }

}

После успешной отправки в списке интерфейсов будет отображаться следующая информация об интерфейсе;

Ознакомьтесь с деталями интерфейса, он по-прежнему очень всеобъемлющий, и интерфейс неплохой!

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

Если мы хотим установить заголовки общедоступных запросов, например, для аутентификации входаAuthorizationголова, может быть模块配置настроить в;

Прежде чем внутренний интерфейс будет завершен, если нам нужны фиктивные данные, мы можем использовать фиктивную функцию;

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

Использовать со смарт-документом

smart-doc — это инструмент для создания документов API без добавления аннотаций."Учебное пособие по умному документу", здесь он используется вместе с Torna.

Сначала изменитьmall-tiny-smart-docКонфигурационный файл смарт-документа проектаsmart-doc.json, добавьте следующую конфигурацию Torna;

{
  // torna平台对接appKey
  "appKey": "20211103905498418195988480",
  //torna平台appToken
  "appToken": "b6c50f442eb348f48867d85f4ef2eaea",
  //torna平台secret
  "secret": "~#ZS~!*2B3I01vbW0f9iKH,rzj-%Xv^Q",
  //torna平台地址，填写自己的私有化部署地址
  "openUrl": "http://localhost:7700/api",
  //测试项目接口环境
  "debugEnvName":"测试环境",
  //测试项目接口地址
  "debugEnvUrl":"http://localhost:8088"
}

Поскольку плагин Maven смарт-док уже имеет функцию отправки документов в Torna, мы просто дважды щелкаемsmart-doc:torna-restкнопка;

Далее в Torna мы можем посмотреть соответствующую документацию по интерфейсу, что очень удобно!

Суммировать

Когда инструмент становится все популярнее, но какие-то функциональные требования не могут быть выполнены, часто выпускаются какие-то усовершенствованные инструменты, Torna — такой инструмент для Swagger. Интерфейс документов Torna и функции отладки, очевидно, намного выше, чем у Swagger, а также добавлены функции управления разрешениями, что значительно повышает безопасность документов.Если вы думаете, что это хорошо, вы можете попробовать!

использованная литература

Официальная документация:torna.cn/

Адрес исходного кода проекта

GitHub.com/macro-positive/…

Эта статьяGitHubGitHub.com/macro-positive/…Записано, приветствую всех на Star!