Сваггер је бесплатан оквир отвореног кода за креирање интерактивне и корисничке АПИ документације. Он генерише интерактивне веб странице које вам омогућавају да тестирате АПИ са различитим улазима.
Сваггер подржава и ЈСОН и КСМЛ корисна оптерећења. Документација коју генерише је погодна за програмере и оне који нису програмери.
Можете да документујете своје НестЈС веб АПИ-је преко Сваггер-а користећи једноставне декоратере, без потребе да напуштате свој ИДЕ.
Корак 1: Генерисање АПИ-ја
Пре него што почнете, морате да креирате демо АПИ за који ће Сваггер генерисати своју документацију.
Демо АПИ ћете генерисати од нуле користећи НестЈС ЦЛИ.
Прво, генеришите нови НестЈС пројекат тако што ћете покренути:
гнездо ново <назив вашег пројекта>
Затим промените директоријум у свој већ креирани пројекат тако што ћете покренути:
цд <назив вашег пројекта>
Затим ћете генерисати РЕСТ АПИ са ЦЛИ тако што ћете покренути:
Нест Генерисати ресурсе демо --но-спец
Видећете упит са питањем „Који транспортни слој користите?“ изаберите РЕСТ АПИ.
Видећете други упит са питањем: „Да ли желите да генеришете ЦРУД улазне тачке?“ Тип И и ударио Ентер.
Наредба изнад генерише потпуно функционалан РЕСТ АПИ са ЦРУД крајњим тачкама и без датотека теста јединице. Отуда --но-спец заставицу у горњој команди.
Корак 2: Инсталирајте Сваггер
Инсталирајте Сваггер и његову Екпресс УИ библиотеку тако што ћете покренути:
нпм инсталирај--саве @нестјс/сваггер сваггер-уи-екпресс
Корак 3: Конфигуришите Сваггер
У вашем маин.тс датотека, увоз СваггерМодуле и ДоцументБуилдер из @нестјс/сваггер.
ДоцументБуилдер помаже у структурирању основног документа. Пружа неколико метода које можете спојити заједно и затворити са градити методом.
Ове методе омогућавају конфигурацију многих атрибута, као што су наслов, опис и верзија.
Створити цонфиг променљива објекта у вашем боотстрап функционише овако:
конст цонфиг = Нова ДоцументБуилдер()
.сетТитле('Демо АПИ')
.сетДесцриптион('Демо АПИ са ЦРУД функционалност')
.сетВерсион('1.0')
.буилд();
Нова инстанца ДоцументБуилдер-а креира основни документ који одговара ОпенАПИ спецификација. Затим можете користити ову инстанцу да поставите наслов, опис и верзију путем одговарајућих метода.
Затим ћете морати да креирате комплетан документ са свим ХТТП рутама дефинисаним помоћу основног документа.
Да бисте то урадили, позовите цреатеДоцумент метод на СваггерМодуле. цреатеДоцумент прихвата два аргумента: инстанцу апликације и објекат опција Сваггер. Сачувајте резултат овог позива у променљивој за каснију употребу:
констдокумент = СваггерМодуле.цреатеДоцумент (апликација, конфигурација);
Затим позовите подесити метод на СваггерМодуле. Метод подешавања узима три аргумента:
- Путања Сваггер корисничког интерфејса. По конвенцији, можете користити „апи“.
- Инстанца апликације
- Комплетан документ
Поред тога, метода подешавања узима опциони објекат опција. Видите НестЈС-ова документација о опцијама Сваггер документа да бисте сазнали више о томе.
Овако:
СваггерМодуле.сетуп('апи', апликација, документ);
Покрените апликацију и идите на http://localhost:
Требало би да видите Сваггер кориснички интерфејс приказан на страници.
Слика изнад је подразумевани приказ корисничког интерфејса Сваггер-а, са дефинисаним свим ХТТП рутама у вашем контролеру. Мораћете да га прилагодите тако да одговара вашој АПИ функционалности.
Корак 4: Прилагодите својства АПИ-ја
Подразумевано, Сваггер ставља префикс за цео одељак ХТТП руте са насловом који гласи „подразумевано“. Ово можете променити тако што ћете означити своју класу контролера са @АпиТагс декоратер и прослеђивање жељене ознаке као аргумента.
Овако:
// демо.цонтроллер.тс
увоз { АпиТагс } из '@нестјс/swagger';
@АпиТагс('Демо')
@Цонтроллер('демо')
извозкласа ДемоЦонтроллер {
Одељак Шеме садржи објекте за пренос података у вашем АПИ-ју. Тренутно, кориснички интерфејс не укључује ниједно од њихових својстава.
Да бисте објавили њихова својства у корисничком интерфејсу, једноставно додајте декоратере. Означите свако тражено својство са @АпиПроперти декоратер. Означите опциона својства са @АпиПропертиОптионал декоратер.
На пример:
// цреате-демо.дто.тс
увоз { АпиПроперти, АпиПропертиОптионал } из '@нестјс/swagger';
извозкласа ЦреатеДемоДто {
@АпиПроперти({
тип: Низ,
опис: 'Ово је обавезно својство',
})
имовина: низ;
@АпиПропертиОптионал({
тип: Низ,
опис: 'Ово је опционо својство',
})
опционо својство: низ;
}
Сваки @АпиПроперти и @АпиПропертиОптионал декоратери прихватају објекат опција. Тај објекат описује својство које следи у наставку.
Имајте на уму да објекат опција користи ЈаваСцрипт, а не ТипеСцрипт. Отуда декларације типа ЈаваСцрипт (тј. Стринг, а не стринг).
Означавање својстава објекта за пренос података додаје пример очекиваних података у одељак Шеме. Такође ажурира придружену ХТТП руту примером очекиваних података.
Корак 5: Подесите одговоре АПИ-ја
У својој класи контролера користите @АпиРеспонсе декоратери да документују све потенцијалне одговоре за сваку ХТТП руту. За сваку крајњу тачку, различити @АпиРеспонсе декоратори описују тип одговора који се очекује.
Објаснили смо уобичајени ХТТП одговори, у случају да нисте упознати са њиховим значењем.
@АпиРеспонсе декоратери прихватају опциони објекат који описује одговор.
Уобичајени ПОСТ одговори
За ПОСТ захтев, вероватни одговори укључују:
- АпиЦреатедРеспонсе, за успешан 201 креиран одговор.
- АпиУнпроцессаблеЕнитиРеспонсе, за неуспела 422 необрадива одговора ентитета.
- АпиФорбидденРеспонсе, за 403 забрањена одговора.
На пример:
// демо.цонтроллер.тс
@Пошта()
@АпиЦреатедРеспонсе({ опис: 'Успешно креирано' })
@АпиУнпроцессаблеЕнтитиРеспонсе({ опис: 'Лош захтев' })
@АпиФорбидденРеспонсе({ опис: 'Неовлашћени захтев' })
Креирај(@Боди() цреатеДемоДто: ЦреатеДемоДто) {
повратаково.демоСервице.цреате (цреатеДемоДто);
}
Уобичајени ГЕТ одговори
За ГЕТ захтеве, вероватни одговори укључују:
- АпиОкРеспонсе, за 200 ок одговора.
- АпиФорбидденРеспонсе, за 403 забрањена одговора.
- АпиНотФоундРеспонсе, за 404 одговора који нису пронађени.
На пример:
// демо.цонтроллер.тс
@Добити()
@АпиОкРеспонсе({ опис: 'Ресурси су успешно враћени' })
@АпиФорбидденРеспонсе({ опис: 'Неовлашћени захтев' })
финдАлл() {
повратаково.демоСервице.финдАлл();
}
@Добити(':ид')
@АпиОкРеспонсе({ опис: 'Ресурс је успешно враћен' })
@АпиФорбидденРеспонсе({ опис: 'Неовлашћени захтев' })
@АпиНотФоундРеспонсе({ опис: 'Ресурс није пронађен' })
наћи један(@Парам('урадио сам: низ) {
повратаково.демоСервице.финдОне(+ид);
}
Уобичајени одговори за ПАТЦХ и УПДАТЕ
За захтеве ПАТЦХ и УПДАТЕ, вероватни одговори укључују:
- АпиОкРеспонсе, за 200 ок одговора.
- АпиНотФоундРеспонсе, за 404 одговора који нису пронађени.
- АпиУнпроцессиблеЕнтитиРеспонсе, за неуспела 422 необрадива одговора ентитета.
- АпиФорбидденРеспонсе, за 403 забрањена одговора.
На пример:
// демо.цонтроллер.тс
@Закрпа(':ид')
@АпиОкРеспонсе({ опис: 'Ресурс је успешно ажуриран' })
@АпиНотФоундРеспонсе({ опис: 'Ресурс није пронађен' })
@АпиФорбидденРеспонсе({ опис: 'Неовлашћени захтев' })
@АпиУнпроцессаблеЕнтитиРеспонсе({ опис: 'Лош захтев' })
ажурирање(@Парам('урадио сам: низ, @Боди() упдатеДемоДто: УпдатеДемоДто) {
повратаково.демоСервице.упдате(+ид, упдатеДемоДто);
}
Уобичајени одговори ДЕЛЕТЕ
За захтеве ДЕЛЕТЕ, вероватни одговори укључују:
- АпиОкРеспонсе, за 200 ок одговора.
- АпиФорбидденРеспонсе, за 403 забрањена одговора.
- АпиНотФоундРеспонсе, за 404 одговора који нису пронађени.
На пример:
// демо.цонтроллер.тс
@Делете(':ид')
@АпиОкРеспонсе({ опис: 'Ресурс је успешно враћен' })
@АпиФорбидденРеспонсе({ опис: 'Неовлашћени захтев' })
@АпиНотФоундРеспонсе({ опис: 'Ресурс није пронађен' })
уклонити (@Парам('урадио сам: низ) {
повратаково.демоСервице.ремове(+ид);
}
Ови декоратери попуњавају вашу документацију могућим одговорима. Можете их видети помоћу падајућег менија поред сваке руте.
Преглед ваше документације
Када је подешавање завршено, можете погледати документацију на локални домаћин:
Основе Сваггер АПИ документације су опис, типови одговора и дефиниција шеме. Ово су основне ствари потребне за креирање добре АПИ документације.