Этот случай входит вGitHub.com/Программист-NDS…
Всем привет, я Сяофу~
Несколько дней назад мой маленький друг из фан-группы спросил, какие полезные инструменты для документирования API можно порекомендовать, и я случайно нашел один инструмент, которым я буду делиться с вами в режиме нон-стоп.
ShowDocИнструмент онлайн-документации API, который очень подходит для команд, а также поддерживает использованиеdockerСамодельный документ-сервис, но для удобства демонстрации я напрямую использовал онлайн-сервис платформы. Адрес официального сайта:
https://www.showdoc.com.cn/item/index
можно использоватьmarkdownГрамматика для написания документации API, документации словаря данных, технической документации, онлайнexcelдокументация. Но старший ленивый программист вроде меня на самом деле уделяет больше вниманияshowdocАвтоматическая генерация функций документации, она может автоматически генерировать документацию API из комментариев к коду или с помощьюRunApiКлиент (инструмент отладки API, аналогичный postman) автоматически генерирует документы при отладке интерфейса.
Продемонстрируем с самого начала, посмотрим, где эта штука пригодится?
Знакомство с ШоуДок
ShowDocДля новых проектов вы можете выбрать обычные документы API, онлайн-формы или одностраничные документы (иерархия каталогов не поддерживается), что позволяет устанавливать пароли доступа к документам проекта и настраивать доменные имена.Это не «доменное имя». в прямом смысле, но только в документе Каталог первого уровня добавляется после доменного имени службы, например:
www.showdoc.com.cn/程序员内点事
Существующие проекты можно копировать или импортировать напрямуюPostman,swaggerJson-файл конфигурации интерфейса API. Предоставленный открытый API является ключом к автоматизированному созданию документов, помните, что существуютapi_key,api_tokenЭти два свойства будут подробно рассмотрены позже.
После входа в проект нажмите в правом верхнем углу+редактировать документ,ShowDocНесколько предустановленных шаблонов документов, а также настраиваемые документы можно сохранять в качестве шаблонов; онлайн-поддержкаMockДля сервисов формат данных интерфейса определяется заранее, и сначала предоставляется временный онлайн-интерфейс, чтобы его можно было разрабатывать синхронно с интерфейсом и плавно переключать позже, также есть простая функция онлайн-тестирования API.
Стиль онлайн-стола очень прост
Экспортные документы имеютword,MarkdownДва формата.
Поддержите контроль версий, вы сможете увидеть запись каждой модификации и откатить модификацию любой версии.
При совместном использовании онлайн-документов с другими, если вы не хотите раскрывать весь каталог API, вы можете предоставить общий доступ на одной странице.
увидеть это чувствоshowdocЭто очень распространено. Вроде ничего особенного. Вышеуказанные документы нужно писать вручную. Это громоздко и не рекомендуется. Далее давайте посмотрим, как автоматически генерировать документы.
Автоматически генерировать документацию
showdocСуществует три способа автоматической генерации документации по API:
- Создается автоматически с помощью инструмента Runapi (рекомендовать)
- Автоматически генерируется с использованием комментариев программного кода
- Автоматически генерировать словарь данных
- Напишите свою собственную программу для вызова интерфейса для генерации
Рунапитулс
RunapiЭто ориентированный на интерфейс инструмент разработки и тестирования (который можно рассматривать какPostmanоблегченная версия). Текущая поддержка клиентовwin,mac,linuxПлатформа и онлайн-версия, включая тестирование интерфейса, автоматическое тестирование процессов, фиктивные данные, совместную работу над проектом и другие функции.
невиновныйRunapiиPostmanСравнительное преимущество невелико, иshowdocЭффективность совместного использования более очевидна.runapiПри тестировании интерфейса автоматически генерируется документация API дляshowdoc, также можно поделитьсяshowdocМеханизм управления командой реализует совместную работу нескольких человек.
RunapiКлиенты могут создавать документы интерфейса API с отладкой или документы в формате Markdown.
Например, мы создаем новый проект"程序员内点事", построить три интерфейса соответственно"点在", "在看", "关注”, с последующей быстрой генерацией данных параметров и результатов отклика и их сохранением.
Нажмите в правом верхнем углу文档链接Задайте пароль доступа. Если оставить поле пустым, по умолчанию общедоступный. Скопируйте ссылку на документ и откройте его в браузере. Вы увидите, что документ интерфейса API сгенерирован. runapi также имеет глобальные параметры и изоляцию от среды. фактическиPostmanЭта функция тоже поддерживается, но ведь это не отечественный продукт, и доступ к сети сильно ограничен.
Есть лучшее место,RunapiОн поддерживает сценарии до и после выполнения интерфейса, такие как проверка утверждений данных ответа, а всплывающее окно очень полезно.
комментарии к коду
Запись информации об интерфейсе в комментарии также может автоматически генерировать документацию дляshowdoc, но мне это не очень нравится, в основном потому, что это более навязчиво, что ухудшает читабельность кода, и на это очень неудобно смотреть.
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户注册
* @description 用户注册的接口
* @method post
* @url https://www.showdoc.com.cn/home/user/login
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
public Object register(){
Реализация этого метода также относительно проста, помните, что я упоминал ранее.api_key,api_tokenЭти два свойства сейчас используются, и я буду использовать среду Windows для демонстрации ниже.
Во-первых, у вас должна быть локальная среда git:
https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe
Затем загрузите скрипт, предоставленный официальным сайтом showdoc.
https://www.showdoc.cc/script/showdoc_api.sh
Исправлятьshowdoc_api.sh, заменить нашapi_keyиapi_tokenЗначение переменной и URL-адрес не нужно изменять, если вы не создаете собственную службу документов.
будетshowdoc_api.shПоместите его в каталог вашего проекта, дважды щелкните, чтобы запустить его, скрипт автоматически рекурсивно просканирует все файлы текстового кода в этом каталоге и подкаталогах и сгенерирует документацию по API.
showdoc_api.shСформированный документ будет отправлен вам для заполненияapi_tokenв этом проекте.
Создать словарь данных
Если мы хотим сгенерировать документ словаря данных непосредственно из таблицы словаря базы данных,showdocОн также поддерживается, сначала скачайте скрипт, предоставленный официальным
wget https://www.showdoc.cc/script/showdoc_db.sh
Измените конфигурацию в скрипте, базе данных,api_key,api_tokenи другую информацию, информация о структуре таблицы базы данных синхронизируется сshowdoc.
Имена переменных и пояснения настроены следующим образом
Эффект показан на рисунке ниже, который создает документ словаря таблицы данных, что очень удобно в некоторых конкретных сценариях.
Открытый API
showdocОткрыт API для редактирования документов, и мы можем вызвать API для создания и редактирования документов в коде. Таким образом, использование сцены становится более гибким.
https://www.showdoc.cc/server/api/item/updateByApi
Параметры API следующие, может быть передано содержимое документа, текст в формате уценки или исходный код html.
Протестируйте необходимые параметры для сборки интерфейса и отправьте их с помощью простого онлайн-инструмента отладки API.
{
"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
"api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
"page_title": "xiaofu",
"page_content": "nihao"
}
видеть в
showdocСоздан соответствующий проект с названиемxiaofuдокументация.
сказать слово
сказал раньшеshowdocсуществующая функциональностьpostmanв основном поддерживается, ноpostmanФункции слишком сложны и не лаконичны, вкупе со многими ограничениями, такими как условия сети, эффективность коллаборативного офиса не высока, иRunapiСотрудничатьshowdocВ некоторых сценариях это может значительно повысить эффективность нашей разработки и доставки, поэтому те, которые могут быть сгенерированы автоматически, абсолютно не написаны от руки!
Как бы не бледно ни хвастался BB, он прост в использовании, подходит ли он вам, видно с первого взгляда
Я Сяофу, увидимся в следующий раз~
Разобраны сотни различных технических электронных книг, и нуждающиеся студенты могут их забрать. Техническая группа почти заполнена, и студенты, которые хотят присоединиться, могут добавить меня в друзья, и давайте поговорим о технологиях с большими парнями.