Swagger è un framework open source gratuito per la creazione di documentazione API interattiva e di facile utilizzo. Genera pagine Web interattive che consentono di testare un'API con vari input.
Swagger supporta sia i payload JSON che XML. La documentazione che genera è adatta all'uso da parte di sviluppatori e non sviluppatori.
Puoi documentare le tue API Web NestJS tramite Swagger utilizzando semplici decoratori, senza dover uscire dal tuo IDE.
Passaggio 1: generazione dell'API
Prima di iniziare, devi creare un'API demo che Swagger genererà la sua documentazione.
Genererai l'API demo da zero utilizzando NestJS CLI.
Innanzitutto, genera un nuovo progetto NestJS eseguendo:
nido nuovo <nome-del-tuo-progetto>
Quindi, cambia la directory nel tuo progetto già creato eseguendo:
CD <nome-del-tuo-progetto>
Successivamente, genererai un'API REST con la CLI eseguendo:
Nest genera una demo di risorse --nessuna specifica
Vedrai una query che chiede "Quale livello di trasporto usi?" Selezionare API REST.
Vedrai un'altra query che chiede: "Vuoi generare punti di ingresso CRUD?" Tipo Y e colpisci accedere.
Il comando sopra genera un'API REST completamente funzionale con gli endpoint CRUD e senza i file di unit test. Quindi il --nessuna specifica flag nel comando sopra.
Passaggio 2: installa Swagger
Installa Swagger e la sua libreria Express UI eseguendo:
npm installare--save @nestjs/swagger swagger-ui-express
Passaggio 3: configura Swagger
Nel tuo main.ts archiviare, importare Modulo Swagger e Costruttore di documenti da @nestjs/spavalda.
DocumentBuilder assiste nella strutturazione di un documento di base. Fornisce diversi metodi che puoi concatenare e chiudere con il costruire metodo.
Questi metodi consentono la configurazione di molti attributi, come titolo, descrizione e versione.
Creare un config variabile oggetto nel tuo bootstrap funziona così:
cost configurazione = nuovo Generatore di documenti()
.setTitle('API demo')
.setDescription('Un'API demo insieme a funzionalità CRUD')
.setVersion('1.0')
.costruire();
Una nuova istanza di DocumentBuilder crea un documento di base che corrisponde a Specifica OpenAPI. È quindi possibile utilizzare questa istanza per impostare il titolo, la descrizione e la versione tramite i metodi appropriati.
Successivamente, dovrai creare un documento completo con tutti i percorsi HTTP definiti utilizzando il documento di base.
Per fare ciò, chiama il createDocumento metodo su SwaggerModule. createDocument accetta due argomenti: un'istanza dell'applicazione e un oggetto opzioni Swagger. Memorizza il risultato di questa chiamata in una variabile per un uso successivo:
costdocumento = SwaggerModule.createDocument (app, configurazione);
Quindi, chiama il impostare metodo su SwaggerModule. Il metodo di installazione accetta tre argomenti:
- Il percorso dell'interfaccia utente di Swagger. Per convenzione, puoi usare “api”.
- Un'istanza dell'applicazione
- Il documento completo
Inoltre, il metodo di installazione accetta un oggetto opzioni facoltativo. Vedere La documentazione di NestJS sulle opzioni dei documenti Swagger per saperne di più.
Così:
SwaggerModule.setup('api', app, documento);
Avvia la tua applicazione e vai su http://localhost:
Dovresti vedere l'interfaccia utente di Swagger visualizzata sulla pagina.
L'immagine sopra è la visualizzazione predefinita dell'interfaccia utente di Swagger, con tutti i percorsi HTTP nel controller definiti. Dovrai personalizzarlo per adattarlo alla tua funzionalità API.
Passaggio 4: personalizza le proprietà dell'API
Per impostazione predefinita, Swagger antepone all'intera sezione del percorso HTTP un'intestazione che recita "predefinito". Puoi cambiarlo annotando la tua classe controller con @ApiTag decoratore e passando il tuo tag preferito come argomento.
Così:
// demo.controller.ts
importare {ApiTag} da '@nestjs/swagger';
@ApiTag("Demo")
@Controllore("demo")
esportareclasse DemoController {
La sezione Schemi contiene gli oggetti Trasferimento dati nell'API. Attualmente, l'interfaccia utente non include nessuna delle loro proprietà.
Per dichiarare le loro proprietà nell'interfaccia utente, aggiungi semplicemente decoratori. Annotare ogni proprietà richiesta con il @ApiProperty decoratore. Annota le proprietà facoltative con il @ApiPropertyFacoltativo decoratore.
Per esempio:
// create-demo.dto.ts
importare {ApiProperty, ApiPropertyopzionale} da '@nestjs/swagger';
esportareclasse CreaDemoDto {
@ApiProperty({
genere: Corda,
descrizione: 'Questa è una proprietà obbligatoria',
})
proprietà: corda;
@ApiPropertyFacoltativo({
genere: Corda,
descrizione: 'Questa è una proprietà opzionale',
})
facoltativo Proprietà: corda;
}
I decoratori @ApiProperty e @ApiPropertyOptional accettano ciascuno un oggetto opzioni. Quell'oggetto descrive la proprietà che segue di seguito.
Si noti che l'oggetto options utilizza JavaScript, non TypeScript. Da qui le dichiarazioni di tipo JavaScript (ovvero String, non stringa).
L'annotazione delle proprietà dell'oggetto Trasferimento dati aggiunge un esempio dei dati previsti alla sezione Schemi. Aggiorna anche il percorso HTTP associato con un esempio dei dati previsti.
Passaggio 5: imposta le risposte API
Nella tua classe controller, usa il @ApiResponse decoratori per documentare tutte le potenziali risposte per ogni percorso HTTP. Per ogni endpoint, i diversi decoratori @ApiResponse descrivono il tipo di risposte da aspettarsi.
Abbiamo spiegato risposte HTTP comuni, nel caso non conosci il loro significato.
I decoratori @ApiResponse accettano un oggetto facoltativo che descrive la risposta.
Risposte POST comuni
Per una richiesta POST, le risposte probabili includono:
- ApiCreatedResponse, per 201 risposte create con successo.
- ApiUnprocessableEnityResponse, per 422 risposte di entità non elaborabili non riuscite.
- ApiForbiddenResponse, per 403 risposte vietate.
Per esempio:
// demo.controller.ts
@Inviare()
@ApiCreatedResponse({ descrizione: 'Creato con successo' })
@ApiUnprocessableEntityResponse({ descrizione: 'Richiesta errata' })
@ApiForbiddenResponse({ descrizione: 'Richiesta non autorizzata' })
creare(@Corpo() createDemoDto: CreateDemoDto) {
Restituzionequesto.demoService.create (createDemoDto);
}
Risposte GET comuni
Per le richieste GET, le risposte probabili includono:
- ApiOkResponse, per 200 risposte ok.
- ApiForbiddenResponse, per 403 risposte vietate.
- ApiNotFoundResponse, per 404 risposte non trovate.
Per esempio:
// demo.controller.ts
@Ottenere()
@ApiOkResponse({ descrizione: 'Le risorse sono state restituite correttamente' })
@ApiForbiddenResponse({ descrizione: 'Richiesta non autorizzata' })
trova tutto() {
Restituzionequesto.demoService.findAll();
}
@Ottenere(':id')
@ApiOkResponse({ descrizione: 'La risorsa è stata restituita correttamente' })
@ApiForbiddenResponse({ descrizione: 'Richiesta non autorizzata' })
@ApiNotFoundResponse({ descrizione: 'Risorsa non trovata' })
trova uno(@Param('L'ho fatto: corda) {
Restituzionequesto.demoService.findOne(+id);
}
Risposte comuni di PATCH e UPDATE
Per le richieste PATCH e UPDATE, le risposte probabili includono:
- ApiOkResponse, per 200 risposte ok.
- ApiNotFoundResponse, per 404 risposte non trovate.
- ApiUnprocessibleEntityResponse, per 422 risposte di entità non elaborabili non riuscite.
- ApiForbiddenResponse, per 403 risposte vietate.
Per esempio:
// demo.controller.ts
@Toppa(':id')
@ApiOkResponse({ descrizione: 'La risorsa è stata aggiornata correttamente' })
@ApiNotFoundResponse({ descrizione: 'Risorsa non trovata' })
@ApiForbiddenResponse({ descrizione: 'Richiesta non autorizzata' })
@ApiUnprocessableEntityResponse({ descrizione: 'Richiesta errata' })
aggiornare(@Param('L'ho fatto: corda, @Corpo() updateDemoDto: UpdateDemoDto) {
Restituzionequesto.demoService.update(+id, updateDemoDto);
}
Risposte comuni DELETE
Per le richieste DELETE, le risposte probabili includono:
- ApiOkResponse, per 200 risposte ok.
- ApiForbiddenResponse, per 403 risposte vietate.
- ApiNotFoundResponse, per 404 risposte non trovate.
Per esempio:
// demo.controller.ts
@Elimina(':id')
@ApiOkResponse({ descrizione: 'La risorsa è stata restituita correttamente' })
@ApiForbiddenResponse({ descrizione: 'Richiesta non autorizzata' })
@ApiNotFoundResponse({ descrizione: 'Risorsa non trovata' })
rimuovere(@Param('L'ho fatto: corda) {
Restituzionequesto.demoService.remove(+id);
}
Questi decoratori popolano la tua documentazione con possibili risposte. Puoi visualizzarli utilizzando il menu a discesa accanto a ciascun percorso.
Visualizzazione della documentazione
Al termine della configurazione, è possibile visualizzare la documentazione su host locale:
Gli elementi essenziali della documentazione dell'API Swagger sono la descrizione, i tipi di risposta e la definizione dello schema. Queste sono le cose di base necessarie per creare una buona documentazione API.
