API文件是一格非常重要的一個部分，說老實的任何形式都可以，將你所製作出來的API撰寫別人看得懂的，但寫文件對於工程師來說是一件很麻煩的事情（對於我來說），但是要讓你的API可以讓別人使用，API文件不可或缺，工商一下在 《使用Laravel 8 PHP主流框架打造RESTful API（iT邦幫忙鐵人賽系列書）》中最後一個章節有提到使用 DarkaOnLine/L5-Swagger 可以使用註解的方式在程式碼裡面加上產生文件相關內容 ，再次更深入的分析一下利弊。
最近公司有這樣的需求，所以就花了一點時間，思考了一下，我認為還是把它拆開來比較好，有好有壞，如果拆開來若變更了什麼地方，API文件可能會沒改到，因為常常會發現功能變更以後，但文件跟不上（雖然API不應該這樣變動）。
如果使用自動產生的套件，這樣可以在程式碼中假設是寫在 Controller 裡面，我覺得也不是一個壞事，因為修改的話，也比較會記得修改文件，假設這些註解都寫在Controller，我認為她本來就是在請求來的時候的處理流程，其他的商業邏輯，或者是資料庫查詢，應該另外有Serivce、Repository 來負責，但有一個壞處，我覺得不好排版，然後在同一個專案中塞這麼多東西，因此覺得猜開比較好。
花了一點時間，研究目前撰寫API主流的OPENAPI格式，讓我們自己手動來產生，明天來分享一下怎麼寫。
