使用 Swagger 和 Nest.js 向您的 REST API 添加实时文档

我们需要记录我们的代码和 API。阻碍我们行动的通常是时间，或者我们知道文档和实际代码会发生变化，这比没有文档更糟糕。所以我们需要一个能随我们变化的东西，这个东西就是 Swagger，它允许你针对它运行查询，这是一个额外的好处。

有时候，处理文档的时候就会有这种感觉。你花了那么多时间写文档，然后有人（可能是你，也可能是你的同事）修改了文档，突然之间，你们就不同步了，感觉很艰难，不是吗？

Swagger 是实时文档，它会随着代码的变化而变化。所以希望你读完这篇文章后能尝试一下。

在本文中，我们将展示在 Nest.js 应用中设置 Swagger 是多么简单。只需一个配置项和几个需要记录的 DTO。

我们将展示以下内容：

搭建Nest.js 应用程序和一些所需的构件，例如模块、服务、DTO
设置Swagger 并了解记录端点是多么容易
探索Swaggers 功能，例如执行查询和检查结果
通过向我们的 DTO 添加装饰器来进一步改进我们的文档。

资源

搭建 Nest.js 项目

让我们使用优秀的 Nest CLI 创建一个新的 Nest.js 项目。如果你还没有安装它，请在终端中运行以下命令进行安装：



npm i -g @nestjs/cli

完毕？

好的，很好。我们继续。

要创建一个嵌套项目，我们只需要调用nest new [project name]以下命令：



nest new swagger-demo

它看起来应该是这样的：

下一步是设置路由。让我们以模块化的方式进行操作，创建一个模块、一个服务和一个 DTO。你说要输入很多代码？其实不用，因为我们使用的是 CLI。让我们看看 CLI 能做什么：



nest --help

它告诉我们输入以下内容：



nest generate|g [options] <schematic> [name] [path]

听起来有点神秘，但要创建一个模块，我们需要输入：



nest g mo cats

我们还需要一个控制器来响应我们的请求。因此，代码如下：



nest g co cats

对于服务，我们可以输入：



nest g s cats

关于控制器 + 服务的创建，有两点需要注意。它们是在cats目录下创建的，并且自带测试 :)，而且它们都已在模块中注册，请查看UPDATE最下面一行的内容。

最后，我们要创建一个 DTO，一个用来保存属性的数据传输对象。我们输入以下命令：



nest g cl cat cats

在运行之前，我们先讨论一下要输入的内容。我们要创建一个cl名为catunder path的 class cats。这样做是为了确保所有相关内容最终都集中在一个地方。

使路线正常运行

到目前为止，我们已经有一堆文件，但我们需要路线才能工作，因此我们需要执行以下操作：

id将和添加name到我们的猫模型中
确保服务有一个getCats()返回猫列表的方法
让控制器注入cats服务并调用getCats()
试用我们的 API 并确保其/cats正常工作

`id`在`name`我们的模型中添加

确保src/cats/cat.ts看起来像这样：



export class Cat {
  id: number;
  name: string;
}

更新我们的服务

我们需要添加两个方法getCats()和createCat()，这将确保一旦我们在此添加 Swagger，我们就有一个GET和一个POST请求。



import { Injectable } from '@nestjs/common';
import { Cat } from './cat';

@Injectable()
export class CatsService {
  cats: Array<Cat> = [{ id: 1, name: 'Cat'}];

  getCats() {
    return this.cats;
  }

  createCat(cat: Cat) {
    this.cats = [ ...this.cats, {...cat}];
  }
}

让控制器使用服务

我们的控制器应该是这样的：



import { Controller, Get, Post, Body } from '@nestjs/common';
import { CatsService } from './cats.service';
import { Cat } from './cat';


@Controller('cats')
export class CatsController {
  constructor(private srv: CatsService) {}

  @Get()
  getCats() {
    return this.srv.getCats();
  }

  @Post()
  createCat(@Body() cat: Cat) {
    this.srv.createCat(cat);
  }
}

以上只是确保我们使用我们的CatsService来获取猫列表或添加猫。

尝试一下

在开始显示 Swagger 之前，我们需要确保路由能够正常工作。因此，请运行：



npm start

然后打开浏览器http://localhost:3000/cats。它应该看起来像这样：

添加 Swagger

现在我们将添加 Swagger。为了使 Swagger 正常工作，我们需要执行以下操作：

安装所需的依赖项
配置我们的引导程序以开始使用 Swagger
确保Swagger 在浏览器中呈现

安装 Swagger

我们需要通过NPM使用以下命令进行安装：



npm install --save @nestjs/swagger swagger-ui-express

这样我们就设置好了，现在进入下一步，配置它。

配置

前往main.ts我们的引导文件。在我们的bootstrap()方法中，它目前如下所示：



async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  await app.listen(3000);

app我们需要在声明和调用之间添加以下内容listen()，即：



  const options = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

首先，我们创建一个options对象，该对象获取title、description，version最后调用，build()最终创建一个选项对象。之后，我们通过调用创建一个文档实例createDocument()。SwaggerModule它接受我们的app实例和options我们刚刚创建的对象。最后一步是调用setup()SwaggerModule。第一个参数是路径，这意味着我们将在下找到我们的 API 文档http://localhost:3000/api。下一个参数是我们的app，最后一个参数是文档实例。我们的main.ts现在应该看起来像这样：



// main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

尝试文档

首先启动我们的应用程序



npm start

然后前往http://localhost:3000/api。然后您应该会看到以下内容：

/这和预期的一样。我们在文件中设置了默认路由app.controller。我们还创建了GETfor/cats和POSTalso for /cats。到目前为止一切顺利。

那么，最关键的问题是，它真的有效吗？好吧，我们先GET来/cats

点击Try it out按钮。此时，它会显示Execute按钮，也点击它。它应该会显示以下内容

它返回的是我们的猫咪列表。cURL如果我们想使用它，我们也会得到一个更友好的版本。我们还可以看到返回的具体响应头，以便我们验证。

那我们的 POST 请求呢？好吧，让我们点击它，然后我们的Try it out。

我们得到一个大的编辑窗口，在其中输入一些与我们想要创建的新猫相对应的 JSON，如下所示：



{
  "id": "2",
  "name": "cat2"
}

点击我们的Execute按钮将得到以下响应：

如你所见，我们得到了一个，这意味着我们有了一只新猫。让我们通过在 Swagger 中201点击 our 来确保这一点：GET /cats

成功了，现在有两只猫了。接下来我们看看如何改进。

改进我们的文档

如果我们滚动到 Swagger 文档页面的底部，我们会看到一个 category Models。它包含Cat我们的 DTO 类。然而，它完全是空的，读起来让人有点难受。不过，我们可以轻松解决这个问题。

我们需要做的是使用装饰器@ApiModelProperty()并将其应用于的每个属性Cat，如下所示：

你cats/cat.ts现在看起来应该是这样的：



import { ApiModelProperty } from "@nestjs/swagger";

export class Cat {
  @ApiModelProperty()
  id: number;

  @ApiModelProperty()
  name: string;
}

让我们再次看看我们的应用程序：



npm start

然后http://localhost:3000/api滚动到底部：

现在我们的类属性也包含在文档中了

概括

就这样！我们又有机会使用可爱的 Nest 了。这次我们用了一些额外的命令来学习如何搭建所有需要的文件。最重要的是，我们学会了如何使用 Swagger 来编写 API 文档。那些随着代码变化而变化的文档值得保留。所以，也给你的 API 准备一些文档吧。

文章来源：https://dev.to/itnext/adding-live-documentation-to-your-rest-api-with-swagger-and-nest-js-211e

使用 Swagger 和 Nest.js 向您的 REST API 添加实时文档

使用 Swagger 和 Nest.js 向您的 REST API 添加实时文档

资源

搭建 Nest.js 项目

使路线正常运行

id在name我们的模型中 添加

更新我们的服务

让控制器使用服务

尝试一下

添加 Swagger

安装 Swagger

配置

尝试文档

改进我们的文档

概括

`id`在`name`我们的模型中添加