Недавно мы наткнулись на Commander, который представляет собой пакет на основе CLI для проектов Node.
Поскольку документация уже перегружена, а кодовая база постоянно растет, что не показывает никаких признаков улучшения удобных для чтения комментариев или документации, мы подумали, что пришло время поискать несколько легкодоступных пакетов npm и начать создавать мини-решение, которое могло бы помочь в покрытии некоторые важные API для наших замечательных разработчиков. commander определенно был одним из тех пакетов, которые выглядели многообещающе.
Чтобы начать работу с Commander в проекте на основе узла, выполните следующую команду:
npm i commander
Когда это будет сделано, мы установили пакет command. С помощью этого пакета вы можете передавать аргументы и параметры на основе CLI, чтобы выполнить некоторую работу, относящуюся к вашей кодовой базе. Это может быть что угодно, например. проверка сведений о базе данных, печать переменных среды, запуск автоматизации и так далее. Мы решили распечатать некоторые метаданные для проекта узла. Метаданные — это не что иное, как некоторые подробности об API, которые присутствовали в кодовой базе, и именно так мы создаем мини-систему документации.
Фрагмент ниже показывает несколько опций на основе CLI, которые мы создали с помощью Commander, что помогает нам документировать наши API.
const { program } = require('commander');
program.version('0.0.1');
const docMethods = require('./index');
const apiFileName = 'apidocs.json';
program
.option('-p, --port', 'display port number of this api.')
.option('-f, --file', 'display file name where api documentations are written.')
.option('-l, --list', 'list all apis.')
.option('-e, --explain <items>', 'explain API(s), you can provide a single value or comma seperates string values for mutitple APIs.')
.option('-d, --describe item', 'describe / change an API description.');
program.parse(process.argv);
const options = program.opts();
if (options.port) console.log(`Port Number is : ${docMethods.port}`);
if (options.file) console.log(`API documentation file is : ${docMethods.apiDocsFileName}`);
if (options.list) docMethods.manageAPIDocs(null, 'list');
if (options.explain) docMethods.manageAPIDocs(options.explain, 'explain');
Объяснение кода
Все, что находится в функции .option(), на самом деле представляет собой простой оператор для создания опции CLI, например:
.option('-p, --port', 'display port number of this api.')
используется для создания параметра, который показывает сведения о номере порта для соответствующей кодовой базы узла. Чтобы запустить эту опцию из интерфейса командной строки, мы использовали следующую команду (большая часть этой команды видна в файле package.json, а сведения о кодовой базе представлены ближе к концу этой статьи):
npm run docs -- -p
вывод:
Port Number is : 3000
Не знаете команды? Командир снова помогает!
С помощью приведенной ниже команды командир распечатывает все доступные команды CLI, которые мы создали, и помогает вам в их использовании:
npm run docs -- -h
Результат — это, по сути, параметры CLI, которые мы создали сами!:
Usage: docs [options] Options: -V, --version output the version number -p, --port display port number of this api. -f, --file display file name where api documentations are written. -l, --list list all apis. -e, --explain <items> explain API(s), you can provide a single value or comma seperates string values for mutitple APIs. -d, --describe item describe / change an API description. -h, --help display help for command
Как же Commander помог создать систему документации?
Вы, наверное, уже догадались, что при использовании Commander мы просто использовали этот пакет для вывода деталей нашего API на консоль. Но как мы собирали сведения об API, удаляли неиспользуемые сведения об API и добавляли новые сведения об API?
Ну, мы просто использовали файл json, названный в нашем проекте как apidocs.json, и использовали его для документирования любых новых API, которые мы создали. API были созданы с помощью Express, и мы использовали промежуточное ПО для записи любых вызовов API и делали запись по умолчанию для API в файле apidocs.json при каждом вызове API.
Позже, когда необходимо изменить сведения об API, пользователь может просто открыть файл apidocs.json и добавить сведения об API.
Обратитесь к приведенному ниже фрагменту функции, который показывает, как мы управляем деталями API в файле json, размещенном в корневом каталоге, с помощью модуля fs:
const manageAPIDocs = (route, type, description = null) => {
if (! fs.existsSync(apiDocsFileName)) {
fs.writeFileSync(apiDocsFileName, JSON.stringify({}));
}
let rawdata = fs.readFileSync(apiDocsFileName);
let apiJSON = JSON.parse(rawdata);
// for adding new APIs in documentation.
if (type === "add") {
if(! (route in apiJSON)) {
let newApiJSON = { ...apiJSON };
newApiJSON[route] = "No information available for this API!";
fs.writeFileSync(apiDocsFileName, JSON.stringify(newApiJSON));
}
}
// for removing 404 APIs from documentation.
if (type === "delete") {
if((route in apiJSON)) {
delete apiJSON[route]
fs.writeFileSync(apiDocsFileName, JSON.stringify(apiJSON));
}
}
// list all APIs.
if(type === "list") {
console.log('All Valid APIs are : \n', Object.keys(apiJSON).join('\n'))
}
// Explain APIs.
if(type === "explain") {
const apiList = route.split(',');
apiList.forEach(api => {
console.log(`${api} : ${apiJSON[api] ? apiJSON[api] : "No information available for this API!"}`);
});
}
}
}
Вот промежуточное ПО, которое использует вышеуказанную функцию для добавления/удаления записи API в файле apidocs.json при каждом вызове API.
// at to the start
function recordAPIDocs (req, res, next) {
manageAPIDocs(req.originalUrl, "add");
next();
}
app.use(recordAPIDocs)
// add this to the last
app.get('*', function(req, res, next){
manageAPIDocs(req.originalUrl, "delete")
next();
});
После этого мы создали мини-систему документации, которая может помочь в получении некоторых сведений об API. Например, используйте следующую команду, запустив кодовую базу после установки npm:
npm run docs -- -e /,as,/get-all-animals
вывод, который мы получаем, — это сведения об API, полученные из файла apidocs.json:
/ : This is the root API as : No information available for this API! /get-all-animals : Get all info for animals from animal-data table
Кодовая база
Кодовая база для этой статьи находится здесь.
Краткое содержание
С помощью commander, fs и express мы можем создать мини-систему документации, которая может не соответствовать стандартам, но уверен, хорошо помогает людям, привыкшим к использованию CLI, изучать и выполнять основные задачи для репозитория кодовой базы унифицированным способом.
