Swagger on ilmainen avoimen lähdekoodin kehys interaktiivisen ja käyttäjäystävällisen API-dokumentaation luomiseen. Se luo interaktiivisia verkkosivuja, joiden avulla voit testata API: ta eri syötteillä.
Swagger tukee sekä JSON- että XML-hyötykuormia. Sen luoma dokumentaatio soveltuu kehittäjien ja ei-kehittäjien käyttöön.
Voit dokumentoida NestJS-verkkosovellusliittymisesi Swaggerin kautta käyttämällä yksinkertaisia koristeita ilman, että sinun tarvitsee poistua IDE: stäsi.
Vaihe 1: Luo API
Ennen kuin aloitat, sinun on luotava esittelysovellusliittymä, jonka Swagger luo dokumentaationsa.
Luot demo-API: n tyhjästä käyttämällä NestJS CLI: tä.
Luo ensin uusi NestJS-projekti suorittamalla:
pesä uusi <projektisi nimi>
Muuta sitten hakemisto jo luotuun projektiisi suorittamalla:
CD <projektisi nimi>
Seuraavaksi luot REST API: n CLI: n kanssa suorittamalla:
pesä luo resurssiesittelyn --ei-spec
Näet kyselyn, jossa kysytään "Mitä kuljetustasoa käytät?" valitse REST API.
Näet toisen kyselyn, jossa kysytään "Haluatko luoda CRUD-tulopisteitä?" Tyyppi Y ja osui Tulla sisään.
Yllä oleva komento luo täysin toimiva REST API CRUD-päätepisteiden kanssa ja ilman yksikkötestitiedostoja. Siksi, --ei-spec lippu yllä olevassa komennossa.
Vaihe 2: Asenna Swagger
Asenna Swagger ja sen Express UI -kirjasto suorittamalla:
npm Asentaa--tallenna @nestjs/swagger swagger-ui-express
Vaihe 3: Määritä Swagger
Sinun main.ts tiedosto, tuonti SwaggerModule ja DocumentBuilder alkaen @nestjs/swagger.
DocumentBuilder auttaa perusasiakirjan jäsentelyssä. Se tarjoaa useita menetelmiä, jotka voit ketjuttaa yhteen ja sulkea rakentaa menetelmä.
Nämä menetelmät mahdollistavat monien määritteiden, kuten otsikon, kuvauksen ja version, määrittämisen.
Luo config objektimuuttujasi bootstrap toimii näin:
konst config = Uusi DocumentBuilder()
.setTitle('Demo API')
.setDescription('A Demo API kanssa CRUD-toiminto")
.setVersion('1.0')
.rakentaa();
Uusi DocumentBuilder-esiintymä luo perusasiakirjan, joka vastaa OpenAPI-määritys. Voit sitten käyttää tätä ilmentymää asettaaksesi otsikon, kuvauksen ja version sopivilla tavoilla.
Seuraavaksi sinun on luotava täydellinen asiakirja, jossa on kaikki HTTP-reitit, jotka on määritetty perusasiakirjan avulla.
Voit tehdä tämän soittamalla numeroon luo asiakirja menetelmä SwaggerModulessa. createDocument hyväksyy kaksi argumenttia: sovellusesiintymän ja Swagger-optioobjektin. Tallenna tämän kutsun tulos muuttujaan myöhempää käyttöä varten:
konstasiakirja = SwaggerModule.createDocument (sovellus, kokoonpano);
Soita seuraavaksi perustaa menetelmä SwaggerModulessa. Asennusmenetelmässä on kolme argumenttia:
- Swaggerin käyttöliittymäpolku. Sopimuksen mukaan voit käyttää "api".
- Sovelluksen esiintymä
- Koko asiakirja
Lisäksi asennusmenetelmä ottaa valinnaisen optionobjektin. Katso NestJS: n dokumentaatio Swaggerin asiakirjavaihtoehdoista saadaksesi lisätietoja siitä.
Niin kuin:
SwaggerModule.setup('api', sovellus, asiakirja);
Aloita hakemuksesi ja siirry osoitteeseen http://localhost:
Sinun pitäisi nähdä Swagger-käyttöliittymä sivulla.
Yllä oleva kuva on Swagger-käyttöliittymän oletusnäkymä, jossa kaikki ohjaimesi HTTP-reitit on määritetty. Sinun on mukautettava se sopimaan API-toimintoihisi.
Vaihe 4: Mukauta API-ominaisuuksia
Oletusarvoisesti Swagger lisää koko HTTP-reitin osion etuliitteen otsikolla, jossa lukee "oletus". Voit muuttaa tätä merkitsemällä ohjainluokkaasi @ApiTags sisustaja ja antamalla haluamasi tagi argumenttina.
Niin kuin:
// demo.controller.ts
tuonti { ApiTags } alkaen '@nestjs/swagger';
@ApiTags("Demo")
@Ohjain('demo')
viedäluokkaa DemoController {
Schemas-osio sisältää sovellusliittymäsi tiedonsiirtoobjektit. Tällä hetkellä käyttöliittymä ei sisällä mitään niiden ominaisuuksista.
Voit ilmoittaa niiden ominaisuudet käyttöliittymässä lisäämällä vain sisustajia. Merkitse jokainen vaadittu ominaisuus @ApiProperty sisustusarkkitehti. Merkitse valinnaiset ominaisuudet @ApiPropertyValinnainen sisustusarkkitehti.
Esimerkiksi:
// create-demo.dto.ts
tuonti { ApiProperty, ApiPropertyOptional } alkaen '@nestjs/swagger';
viedäluokkaa CreateDemoDto {
@ApiProperty({
tyyppi: merkkijono,
kuvaus: "Tämä on pakollinen ominaisuus",
})
omaisuus: merkkijono;
@ApiPropertyValinnainen({
tyyppi: merkkijono,
kuvaus: "Tämä on valinnainen ominaisuus",
})
valinnainenOminaisuus: merkkijono;
}
@ApiProperty- ja @ApiPropertyOptional-sisustajat hyväksyvät kumpikin optioobjektin. Objekti kuvaa alla olevaa ominaisuutta.
Huomaa, että asetukset-objekti käyttää JavaScriptiä, ei TypeScriptiä. Tästä johtuvat JavaScript-tyypin ilmoitukset (eli merkkijono, ei merkkijono).
Tiedonsiirtoobjektin ominaisuuksien merkitseminen lisää esimerkin odotetuista tiedoista Schemas-osioon. Se myös päivittää siihen liittyvän HTTP-reitin esimerkillä odotetusta tiedosta.
Vaihe 5: Aseta API-vastaukset
Käytä ohjainluokassasi @ApiResponse sisustajat dokumentoivat kaikki mahdolliset vastaukset jokaiselle HTTP-reitille. Jokaiselle päätepisteelle eri @ApiResponse-sisustajat kuvaavat odotettavissa olevien vastausten tyypin.
Olemme selittäneet yleisiä HTTP-vastauksia, jos et ole perehtynyt niiden merkitykseen.
@ApiResponse-sisustajat hyväksyvät valinnaisen objektin, joka kuvaa vastausta.
Yleiset POST-vastaukset
POST-pyynnössä todennäköisiä vastauksia ovat:
- ApiCreatedResponse, onnistuneesta 201 luodusta vastauksesta.
- ApiUnprocessableEnityResponse, epäonnistuneille 422 käsittelemättömälle kokonaisuuden vastaukselle.
- ApiForbiddenResponse, 403 kiellettyä vastausta varten.
Esimerkiksi:
// demo.controller.ts
@Lähettää()
@ApiCreatedResponse({ kuvaus: 'Luotu onnistuneesti' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: 'Luvaton pyyntö' })
luoda(@Keho() createDemoDto: CreateDemoDto) {
palataTämä.demoService.create (createDemoDto);
}
Yleiset GET-vastaukset
GET-pyyntöjen osalta todennäköisiä vastauksia ovat:
- ApiOkResponse, 200 ok-vastaukselle.
- ApiForbiddenResponse, 403 kiellettyä vastausta varten.
- ApiNotFoundResponse, 404 ei löytynyt vastausta.
Esimerkiksi:
// demo.controller.ts
@Saada()
@ApiOkResponse({ kuvaus: 'Resurssit palautettiin onnistuneesti' })
@ApiForbiddenResponse({ description: 'Luvaton pyyntö' })
löydä kaikki() {
palataTämä.demoService.findAll();
}
@Saada(':id')
@ApiOkResponse({ kuvaus: 'Resurssi palautettiin onnistuneesti' })
@ApiForbiddenResponse({ description: 'Luvaton pyyntö' })
@ApiNotFoundResponse({ kuvaus: 'Resurssia ei löydy' })
löydä yksi(@Param('minä tein: merkkijono) {
palataTämä.demoService.findOne(+id);
}
Yleiset PATCH- ja UPDATE-vastaukset
PATCH- ja UPDATE-pyyntöjen todennäköisiä vastauksia ovat:
- ApiOkResponse, 200 ok-vastaukselle.
- ApiNotFoundResponse, 404 ei löytynyt vastausta.
- ApiUnprocessibleEntityResponse, epäonnistuneille 422 käsittelemättömälle kokonaisuuden vastaukselle.
- ApiForbiddenResponse, 403 kiellettyä vastausta varten.
Esimerkiksi:
// demo.controller.ts
@Patch(':id')
@ApiOkResponse({ kuvaus: 'Resurssin päivitys onnistui' })
@ApiNotFoundResponse({ kuvaus: 'Resurssia ei löydy' })
@ApiForbiddenResponse({ description: 'Luvaton pyyntö' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
päivittää(@Param('minä tein: merkkijono, @Keho() updateDemoDto: UpdateDemoDto) {
palataTämä.demoService.update(+id, updateDemoDto);
}
Yleiset DELETE-vastaukset
DELETE-pyyntöjen todennäköisiä vastauksia ovat:
- ApiOkResponse, 200 ok-vastaukselle.
- ApiForbiddenResponse, 403 kiellettyä vastausta varten.
- ApiNotFoundResponse, 404 ei löytynyt vastausta.
Esimerkiksi:
// demo.controller.ts
@Poistaa(':id')
@ApiOkResponse({ kuvaus: 'Resurssi palautettiin onnistuneesti' })
@ApiForbiddenResponse({ description: 'Luvaton pyyntö' })
@ApiNotFoundResponse({ kuvaus: 'Resurssia ei löydy' })
Poista(@Param('minä tein: merkkijono) {
palataTämä.demoService.remove(+id);
}
Nämä sisustajat täyttävät dokumentaatiosi mahdollisilla vastauksilla. Voit tarkastella niitä kunkin reitin vieressä olevasta avattavasta valikosta.
Asiakirjojen tarkasteleminen
Kun asennus on valmis, voit tarkastella dokumentaatiota osoitteessa paikallinen isäntä:
Swagger API -dokumentaation olennaiset osat ovat kuvaus, vastaustyypit ja skeeman määritelmä. Nämä ovat perusasiat, joita tarvitaan hyvän API-dokumentaation luomiseen.
