如何撰寫API文件

API文件是一格非常重要的一個部分,說老實的任何形式都可以,將你所製作出來的API撰寫別人看得懂的,但寫文件對於工程師來說是一件很麻煩的事情(對於我來說),但是要讓你的API可以讓別人使用,API文件不可或缺,工商一下在 《使用Laravel 8 PHP主流框架打造RESTful API(iT邦幫忙鐵人賽系列書)》中最後一個章節有提到使用 DarkaOnLine/L5-Swagger 可以使用註解的方式在程式碼裡面加上產生文件相關內容 ,再次更深入的分析一下利弊。

最近公司有這樣的需求,所以就花了一點時間,思考了一下,我認為還是把它拆開來比較好,有好有壞,如果拆開來若變更了什麼地方,API文件可能會沒改到,因為常常會發現功能變更以後,但文件跟不上(雖然API不應該這樣變動)。

如果使用自動產生的套件,這樣可以在程式碼中假設是寫在 Controller 裡面,我覺得也不是一個壞事,因為修改的話,也比較會記得修改文件,假設這些註解都寫在Controller,我認為她本來就是在請求來的時候的處理流程,其他的商業邏輯,或者是資料庫查詢,應該另外有Serivce、Repository 來負責,但有一個壞處,我覺得不好排版,然後在同一個專案中塞這麼多東西,因此覺得猜開比較好。

花了一點時間,研究目前撰寫API主流的OPENAPI格式,讓我們自己手動來產生,明天來分享一下怎麼寫。

發佈留言