Swagger 搭建 API 文档管理平台

栏目: 服务器 · 发布时间: 6年前

内容简介:API 文档是前后端对接的基本,但如果还停留在手写文档的阶段,那就真的太 out 了。大家可能也尝试过各种 API 接口管理的工具,比如 postman 、apizza 等,但个人使用下来还是感觉麻烦了,长期来看我是拒绝的。从目前 API 文档生成及管理上来看,Swagger 可算是不错的框架。今天来介绍一下 Swagger 的使用,以下使用 .NETCore Web API 为例,其他语言也类似,最终都是依赖生成的 json/yaml 文件。

API 文档是前后端对接的基本,但如果还停留在手写文档的阶段,那就真的太 out 了。大家可能也尝试过各种 API 接口管理的工具,比如 postman 、apizza 等,但个人使用下来还是感觉麻烦了,长期来看我是拒绝的。

Swagger 搭建 API 文档管理平台

从目前 API 文档生成及管理上来看,Swagger 可算是不错的框架。今天来介绍一下 Swagger 的使用,以下使用 .NETCore Web API 为例,其他语言也类似,最终都是依赖生成的 json/yaml 文件。

文档生成

内嵌代码方式

  1. 新建 ASP.NET Core Web 应用程序,选择 API 类型

  2. Nuget 安装 Swashbuckle.AspNetCore

    Install-Package Swashbuckle.AspNetCore
    
  3. 在 Startup.cs 中的 ConfigureServices 和 Configure 方法添加 Swagger 相关代码

    public void ConfigureServices(IServiceCollection services)
    {
    	services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
           
    	// swagger.json 文档生成参数配置
    	services.AddSwaggerGen(options =>
    	{
    		options.SwaggerDoc("v1", new Info
    		{
    			Title = "SwaggerTest接口文档",
    			Version = "1.0.0"
    		});
    		
    		options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SwaggerTest.XML"));
    	});
    }
    
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    	if (env.IsDevelopment())
    	{
    		app.UseDeveloperExceptionPage();
    	}
    
    	app.UseMvc();
    
    	app.UseSwagger();
    	
    	// 通过SwaggerUI展示
    	app.UseSwaggerUI(options =>
    	{
    		options.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerTest");
    	});
    }
    
  4. 项目属性中的 ”生成“ 勾选 “XML 文档文件” ( Debug 和 Release 两种模式下都勾选上 )。这一步的目的是将代码注释生成文档,所以接口方法及参数都务必加上完整的注释

    Swagger 搭建 API 文档管理平台

以上方式使用起来非常简单,但个人觉得存在以下问题:

  1. Startup 中需要加入 Swagger 相关的一些代码,不够整洁

  2. 如果有多个 API 服务,每个服务都需要添加类似代码,而且每个服务的文档地址独立,不能统一管理

非内嵌代码方式

Swagger UI 本身是一个可以单独使用的前端项目。从 UseSwaggerUI 的参数配置来看:

app.UseSwaggerUI(options =>
{
	options.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerTest");
});

其实只要将 “/swagger/v1/swagger.json” 这个文件引用进去即可,所以只需存在一种可以根据项目的 dll 文件生成 swagger.json 的方式,然后把生成的 swagger.json 引用到 Swagger UI 。 NSwag 恰好可以满足这个需求。

抛开内嵌代码的方式,假设现在是一个全新的 Web API 项目。

  1. 下载 NSwag ,在 Downloads 中下载 NSwag command line tools。如下载后解压地址为: C:\Users\Administrator\Downloads\NSwag\

  2. 在项目根目录下新建 bat 文件并添加脚本,执行生成 swagger.json ( windows 环境

    :: 生成的文档名,每个项目最好是唯一的
    SET FILE_NAME=swaggerTest
    :: 项目dll地址
    SET SOURCE_DLL=bin\Release\netcoreapp2.1\publish\SwaggerTest.dll
    :: 文档生成的目标文件夹
    SET TARGET_DIR=D:\ApiDoc\public\docs\
    
    :: Swagger文档配置
    
    :: 标题
    SET TITLE=SwaggerTest接口文档
    :: 描述
    SET DESCRIPTION=SwaggerTest接口文档描述
    :: 版本
    SET VERSION=1.0.0
    :: 接口测试请求的host地址,不同的api服务有不同的host
    SET HOST=localhost:5000
    
    :: 通过 dotnet-nswag 执行生成命令
    dotnet C:\Users\Administrator\Downloads\NSwag\NetCore21\dotnet-nswag.dll webapi2swagger /assembly:"%SOURCE_DLL%" /AspNetCore:true /output:%TARGET_DIR%%FILE_NAME%.json /InfoTitle:"%TITLE%" /InfoDescription:"%DESCRIPTION%" /InfoVersion:%VERSION% /ServiceHost:%HOST%
    

bat 脚本执行完成后,在 D:\ApiDoc\public\docs\ 目录下就会多出一个 swaggerTest.json,以这种方式我们并不需要修改任何代码。到目前为止,API 文档对应的 json 文件就有了,接下来就是把它通过 Swagger UI 展示出来。假设每个 API 项目都生成一个 json 文件到指定的目录,而 Swagger UI 本身支持配置多个文档 url 地址,这就意味着可以搭建出了一个 API 文档管理平台。

Swagger 搭建 API 文档管理平台

文档管理

  1. 下载 Swagger UI 并解压

  2. 搭建一个 Node.js 项目,可使用 Express 或者 Koa 框架(其他语言的项目也可以,任意选择)

    1. 将 swagger-ui dist 文件夹下的文件全部复制到项目的 public 文件夹下

    2. 安装 express

    3. 新建 index.js,添加如下代码

      const express = require('express');
      const app = express();
      
      app.use('/', express.static('public'));
      
      app.listen(3000, function () {
      	console.log('app listening on http://localhost:3000');
      });
      
    4. 启动服务

      node index.js
      

完成以上步骤,Swagger UI 的站点就搭建完成了,访问 http://localhost:3000 会出现一个默认的 API 接口文档页面。

打开 public/index.html 会发现有这么一段代码:

const ui = SwaggerUIBundle({
	url: "https://petstore.swagger.io/v2/swagger.json",
	...
})

这里的 url 配置了一个默认的 swagger.json文件的地址,所以我们只需要把 url 替换成上面生成的 swaggerTest.json 地址就可以了,将 swaggerTest.json 复制到 public/docs 目录下

Swagger 搭建 API 文档管理平台

const ui = SwaggerUIBundle({
    url: "./docs/swaggerTest.json",
    ...
})

Swagger 搭建 API 文档管理平台

如果有多个 json 文件就不能使用 url 参数,需要修改成 urls 参数,具体可参考 Swagger UI 参数配置 ,为了不需要每次手动调整 urls,所以需要动态读取 docs 文件夹下的文件,生成的文档只需要传到这个目录下就可以直接查看和测试。

在 index.js 增加一个接口:

app.get('/getDocs', function (req, res) {
    let docFileInfos = [];
    let pathDir = __dirname + '/public/docs';
    try {
        let fileNames = fs.readdirSync(pathDir);
        fileNames.forEach(function (fileName) {
            let data = fs.readFileSync(pathDir + '/' + fileName, 'utf8');
            data = data.trim();
            let json = JSON.parse(data);
            docFileInfos.push({
                url: './docs/' + fileName,
                name: json.info.title
            });
        });
    } catch (err) {
        console.log(err);
    }
    res.send(docFileInfos);
});

public/index.html 引入 axios,并调用 getDocs 接口获取结果,将 response.data 赋给 SwaggerUIBundle 的 urls 参数。

axios.get('/getDocs')
	.then(function (response) {
		if (response.status === 200 && response.data.length) {
			...
		}
	});

当存在多个 json 文件的时候,可以从下拉选项中进去切换

Swagger 搭建 API 文档管理平台

参考链接


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

大数据之路

大数据之路

阿里巴巴数据技术及产品部 / 电子工业出版社 / 2017-7-1 / CNY 79.00

在阿里巴巴集团内,数据人员面临的现实情况是:集团数据存储已经达到EB级别,部分单张表每天的数据记录数高达几千亿条;在2016年“双11购物狂欢节”的24小时中,支付金额达到了1207亿元人民币,支付峰值高达12万笔/秒,下单峰值达17.5万笔/秒,媒体直播大屏处理的总数据量高达百亿级别且所有数据都需要做到实时、准确地对外披露……巨大的信息量给数据采集、存储和计算都带来了极大的挑战。 《大数据......一起来看看 《大数据之路》 这本书的介绍吧!

Markdown 在线编辑器
Markdown 在线编辑器

Markdown 在线编辑器

html转js在线工具
html转js在线工具

html转js在线工具

HEX HSV 转换工具
HEX HSV 转换工具

HEX HSV 互换工具