引入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;
/// <author>cxg 2022-6-18</author>
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<TGoods>;
{$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<TGoodsAPI>;
end.