创建“Insomnia优先”的Swagger页面

今天，我想向大家展示如何创建一个“Insomnia优先”的swagger页面，让你的API可以一键轻松地被Insomnia使用。

嘿！我没有失眠症！

当你在这里读到insomnia时，我猜你可能会想到失眠的夜晚，或者90年代那首流行的歌曲——但实际上我指的是Insomnia这个REST客户端。没错！Postman让一让，你遇到了竞争对手了！

等等，Postman有什么问题？

对标签的痴迷？笨拙的用户体验？启动速度慢？别误会，我认为Postman提供了一个非常强大的产品，对于合适的任务来说是一个有用的工具。特别是他们的测试运行器功能非常全面，并且可能是每个QA/QE工具箱中的必备品。但对于我们软件开发者来说，我认为它过于复杂。Insomnia启动更快，更易于导航，更易于使用——恕我直言。

好的 - 这和Swagger有什么关系？

看到这个漂亮的在Insomnia中运行按钮了吗？当你点击它时，Insomnia会打开并询问你是否要导入集合，从而非常容易地构建一个全面的API端点集合。告别逐个导入curl命令吧。

令人印象深刻！我们如何添加这个按钮？

访问https://insomnia.rest/create-run-button并输入你的API设置。导入URL可能取决于你的实现。对于dotnet项目，这通常是一个swagger.json文件。由于这个例子是一个运行在express上的NestJS项目，swagger模式可以在一个api-json端点下获取。

无论如何，你想要做的是获取上一页为你生成的HTML片段，并将其设置为你的swagger规范的description。如何做到这一点当然也会因你的技术栈而异，但在NestJS中，一个完整的swagger配置示例可能如下所示（在main.ts中）

  const app = await NestFactory.create(AppModule);

  // Swagger setup
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('My API specification')
    .setVersion('1.0')
    .addTag('app', '')
    .setDescription('<a href="https://insomnia.rest/run/?label=My%20API&
                      uri=http%3A%2F%2Flocalhost%3A3001%2Fapi-json" target="_blank">
         <img src="https://insomnia.rest/images/run.svg" alt="Run in Insomnia"></a>')
    .build();
  
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
  
  await app.listen(3001);

而且因为description只是HTML，所以你当然可以在按钮之前或之后添加内容。

结果如何？

如你所见，我的端点（带有示例主体和其他变量，如baseUrl）已被导入，包含在一个文件夹中，该文件夹由swagger规范中的tag标识。这可能只有一个端点看起来并不令人印象深刻——但想象一下一个包含六个（或更多）标签和数十个端点的真实应用程序。能够一键将整个内容导入到你的REST客户端，这真是太酷了！更重要的是，它不仅仅是任何REST客户端——它是Insomnia！😎

好了，今天就到这里。祝你编码愉快！