Swagger é uma estrutura gratuita e de código aberto para criar documentação de API interativa e fácil de usar. Ele gera páginas da web interativas que permitem testar uma API com várias entradas.
O Swagger oferece suporte a cargas úteis JSON e XML. A documentação que ele gera é adequada para desenvolvedores e não desenvolvedores usarem.
Você pode documentar suas APIs da Web NestJS via Swagger usando decoradores simples, sem precisar sair do seu IDE.
Etapa 1: gerar a API
Antes de iniciar, você deve criar uma API de demonstração que o Swagger irá gerar sua documentação.
Você gerará a API de demonstração do zero usando a CLI do NestJS.
Em primeiro lugar, gere um novo projeto NestJS executando:
ninho novo <nome-do-seu-projeto>
Em seguida, altere o diretório para o seu projeto já criado executando:
cd <nome-do-seu-projeto>
Em seguida, você gerará uma API REST com a CLI executando:
aninhar gerar demonstração de recursos --sem especificação
Você verá uma consulta perguntando: "Qual camada de transporte você usa?" selecionar API REST.
Você verá outra consulta perguntando: "Você gostaria de gerar pontos de entrada CRUD?" Modelo S e bater Digitar.
O comando acima gera uma API REST totalmente funcional com terminais CRUD e sem os arquivos de teste de unidade. Daí, o --sem especificação flag no comando acima.
Etapa 2: instalar o Swagger
Instale o Swagger e sua biblioteca Express UI executando:
npm instalar--save @nestjs/swagger swagger-ui-express
Etapa 3: configurar o Swagger
Na tua main.ts arquivo, importação SwaggerModule e DocumentBuilder a partir de @nestjs/swagger.
O DocumentBuilder auxilia na estruturação de um documento base. Ele fornece vários métodos que você pode encadear e fechar com o construir método.
Esses métodos permitem a configuração de vários atributos, como título, descrição e versão.
Crie um configuração variável de objeto em seu inicialização funcionar assim:
const configuração = novo DocumentBuilder()
.setTitle('API de demonstração')
.setDescription('Uma API de demonstração com Funcionalidade CRUD')
.setVersion('1.0')
.construir();
Uma nova instância do DocumentBuilder cria um documento base que corresponde ao Especificação OpenAPI. Você pode usar essa instância para definir o título, a descrição e a versão por meio de seus métodos apropriados.
Em seguida, você precisará criar um documento completo com todas as rotas HTTP definidas usando o documento base.
Para isso, ligue para o criar documento método no SwaggerModule. createDocument aceita dois argumentos: uma instância do aplicativo e um objeto de opções do Swagger. Armazene o resultado desta chamada em uma variável para uso posterior:
constdocumento = SwaggerModule.createDocument (aplicativo, configuração);
A seguir, chame o configurar método no SwaggerModule. O método setup recebe três argumentos:
- O caminho da interface do usuário do Swagger. Por convenção, você pode usar “api”.
- Uma instância de aplicativo
- O documento completo
Além disso, o método de configuração usa um objeto de opções opcional. Ver Documentação do NestJS sobre opções de documentos Swagger para aprender mais sobre isso.
Igual a:
SwaggerModule.setup('api', aplicativo, documento);
Inicie seu aplicativo e vá para http://localhost:
Você deve ver a interface do usuário do Swagger exibida na página.
A imagem acima é a visualização padrão da interface do usuário do Swagger, com todas as rotas HTTP em seu controlador definidas. Você precisará personalizá-lo para se adequar à funcionalidade da sua API.
Etapa 4: personalizar as propriedades da API
Por padrão, o Swagger prefixa toda a seção de rota HTTP com um título que diz “padrão”. Você pode alterar isso anotando sua classe de controlador com o @ApiTags decorador e passando sua tag preferida como argumento.
Igual a:
// demo.controller.ts
importar {ApiTags} a partir de '@nestjs/swagger';
@ApiTags('Demonstração')
@Controlador('demonstração')
exportarclasse DemoController {
A seção Esquemas contém os objetos de transferência de dados em sua API. Atualmente, a interface do usuário não inclui nenhuma de suas propriedades.
Para declarar suas propriedades na interface do usuário, basta adicionar decoradores. Anote cada propriedade necessária com o @ApiProperty decorador. Anote propriedades opcionais com o @ApiPropertyOpcional decorador.
Por exemplo:
// cria-demo.dto.ts
importar { ApiProperty, ApiPropertyOpcional } a partir de '@nestjs/swagger';
exportarclasse CreateDemoDto {
@ApiProperty({
modelo: Corda,
descrição: 'Esta é uma propriedade obrigatória',
})
propriedade: corda;
@ApiPropertyOpcional({
modelo: Corda,
descrição: 'Esta é uma propriedade opcional',
})
propriedade opcional: corda;
}
Os decoradores @ApiProperty e @ApiPropertyOptional aceitam um objeto de opções. Esse objeto descreve a propriedade que segue abaixo.
Observe que o objeto de opções usa JavaScript, não TypeScript. Daí as declarações de tipo JavaScript (ou seja, String, não string).
Anotar as propriedades do objeto Data-transfer adiciona um exemplo dos dados esperados à seção Schemas. Ele também atualiza a rota HTTP associada com um exemplo dos dados esperados.
Etapa 5: definir respostas da API
Na sua classe de controlador, use o @ApiResponse decoradores para documentar todas as respostas potenciais para cada rota HTTP. Para cada endpoint, os diferentes decoradores @ApiResponse descrevem o tipo de resposta a ser esperada.
Nós explicamos respostas HTTP comuns, caso você não esteja familiarizado com o que eles significam.
Os decoradores @ApiResponse aceitam um objeto opcional que descreve a resposta.
Respostas POST comuns
Para uma solicitação POST, as respostas prováveis incluem:
- ApiCreatedResponse, para 201 respostas criadas com sucesso.
- ApiUnprocessableEnityResponse, para 422 respostas de entidade não processáveis com falha.
- ApiForbiddenResponse, para 403 respostas proibidas.
Por exemplo:
// demo.controller.ts
@Publicar()
@ApiCreatedResponse({descrição: 'Criado com sucesso' })
@ApiUnprocessableEntityResponse({ descrição: 'Solicitação inválida' })
@ApiForbiddenResponse({ descrição: 'Solicitação não autorizada' })
crio(@Corpo() createDemoDto: CreateDemoDto) {
Retornaisto.demoService.create (createDemoDto);
}
Respostas GET comuns
Para solicitações GET, as respostas prováveis incluem:
- ApiOkResponse, para 200 respostas ok.
- ApiForbiddenResponse, para 403 respostas proibidas.
- ApiNotFoundResponse, para 404 respostas não encontradas.
Por exemplo:
// demo.controller.ts
@Pegue()
@ApiOkResponse({ description: 'Os recursos foram devolvidos com sucesso' })
@ApiForbiddenResponse({ descrição: 'Solicitação não autorizada' })
encontrar tudo() {
Retornaisto.demoService.findAll();
}
@Pegue(':Eu iria')
@ApiOkResponse({ description: 'O recurso foi retornado com sucesso' })
@ApiForbiddenResponse({ descrição: 'Solicitação não autorizada' })
@ApiNotFoundResponse({descrição: 'Recurso não encontrado' })
encontrarUm(@Param('Eu fiz: corda) {
Retornaisto.demoService.findOne(+id);
}
Respostas comuns de PATCH e UPDATE
Para solicitações PATCH e UPDATE, as respostas prováveis incluem:
- ApiOkResponse, para 200 respostas ok.
- ApiNotFoundResponse, para 404 respostas não encontradas.
- ApiUnprocessibleEntityResponse, para 422 respostas de entidade não processáveis com falha.
- ApiForbiddenResponse, para 403 respostas proibidas.
Por exemplo:
// demo.controller.ts
@Correção(':Eu iria')
@ApiOkResponse({ description: 'O recurso foi atualizado com sucesso' })
@ApiNotFoundResponse({descrição: 'Recurso não encontrado' })
@ApiForbiddenResponse({ descrição: 'Solicitação não autorizada' })
@ApiUnprocessableEntityResponse({ descrição: 'Solicitação inválida' })
atualizar(@Param('Eu fiz: corda, @Corpo() updateDemoDto: UpdateDemoDto) {
Retornaisto.demoService.update(+id, updateDemoDto);
}
Respostas DELETE comuns
Para solicitações DELETE, as respostas prováveis incluem:
- ApiOkResponse, para 200 respostas ok.
- ApiForbiddenResponse, para 403 respostas proibidas.
- ApiNotFoundResponse, para 404 respostas não encontradas.
Por exemplo:
// demo.controller.ts
@Excluir(':Eu iria')
@ApiOkResponse({ description: 'O recurso foi retornado com sucesso' })
@ApiForbiddenResponse({ descrição: 'Solicitação não autorizada' })
@ApiNotFoundResponse({descrição: 'Recurso não encontrado' })
remover(@Param('Eu fiz: corda) {
Retornaisto.demoService.remove(+id);
}
Esses decoradores preenchem sua documentação com possíveis respostas. Você pode visualizá-los usando o menu suspenso ao lado de cada rota.
Visualizando sua documentação
Quando a configuração estiver concluída, você poderá visualizar sua documentação em localhost:
Os fundamentos da documentação da API Swagger são a descrição, os tipos de resposta e a definição do esquema. Essas são as coisas básicas necessárias para criar uma boa documentação de API.