引入OAS3和Swagger全面提升开发者体验

面向web api开发
大家在开发完 webapi 后，经常为了方便接口双方对接，需要将 webapi 接口文档化，那有没有什么快捷可交互的文档呢？可以利用快捷工具 swagger，它的可视化 UI 可轻松助你 API 文档化的同时还方便测试 API。

什么是swagger
swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，swagger 消除了调用服务时可能会有的猜测。

swagger 的优势

支持 API 自动生成同步的在线文档：使用 swagger 后者可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
说白了就是一种接口文档，从而提升web api开发的效率。

一句话： swagger的使用，写好注释就是写好接口文档。

设计好的在线接口文档：http://42.193.160.160:8080/rest/app/openapi/

什么是OAS3
作为一个经常要提供给API文档给内部和第三方的阅读的“苦程”，我一直在寻找一个完美的DELPHI 文档解决方案。使用OAS3 规范管理文档接口，这也是当前OpenApi规范标准。

使用PASCAL语言，设计接口和注释。设计接口彻底摆脱对具体开发框架的依赖，也无需业务感知。让产品经理可以胜任产品的接口设计。

unit server.resources.goods;
/// cxg 2022-6-18

interface

uses
  System.Generics.Collections,
  System.SysUtils, WiRL.Core.Registry, WiRL.Core.Attributes,  WiRL.Core.MessageBody.Default,
  WiRL.http.Accept.MediaType;

{$REGION '返回'}
type
  TResult = record
    status: integer;
    exception: string;
    message: string;
  end;
{$ENDREGION}

{$REGION '商品资料结构定义'}
type
  TGoods = record
    GoodsId: string;
    GoodsName: string;
  end;

type
  TGoodss = TArray;
{$ENDREGION}

{$REGION '商品资料查询结果'}
type
  TGoodsResult = record
    status: integer;
    exception: string;
    message: string;
    data: TGoodss
  end;
{$ENDREGION}

{$REGION '商品资料接口定义'}
type
  [Path('goods')]
  TGoodsAPI = class
    [post, path('/select/{dbid}'), Produces(TMediaType.APPLICATION_JSON)]
    function select([PathParam('dbid')] dbid: string): TGoodsResult;
    [post, path('/insert/{dbid}'), Consumes(TMediaType.APPLICATION_JSON), Produces(TMediaType.APPLICATION_JSON)]
    function insert([PathParam('dbid')] dbid: string; [BodyParam] body: TGoods): TResult;
    [post, path('/update/{dbid}/{goodsid}'), Consumes(TMediaType.APPLICATION_JSON), Produces(TMediaType.APPLICATION_JSON)]
    function update([PathParam('dbid')] dbid: string; [PathParam('goodsid')] goodsid: string; [BodyParam] body: TGoods): TResult;
    [post, path('/delete/{dbid}/{goodsid}'), Produces(TMediaType.APPLICATION_JSON)]
    function delete([PathParam('dbid')] dbid: string; [PathParam('goodsid')] goodsid: string): TResult;
  end;
{$ENDREGION}

implementation

{ TGoodsAPI }

function TGoodsAPI.delete(dbid, goodsid: string): TResult;
begin

end;

function TGoodsAPI.insert(dbid: string; body: TGoods): TResult;
begin

end;

function TGoodsAPI.select(dbid: string): TGoodsResult;
begin

end;

function TGoodsAPI.update(dbid, goodsid: string; body: TGoods): TResult;
begin

end;

initialization
  TWiRLResourceRegistry.Instance.RegisterResource;

end.

openapi

引入OAS3和Swagger全面提升开发者体验

相关

标签