web項(xiàng)目開發(fā)，先讓后端程序員產(chǎn)出接口文檔，是否是開發(fā)流程最合理的選擇？有無更好選擇？利弊是什么？

是不是后端程序員一般會(huì)認(rèn)為先給接口文檔，是對自己不利？

不是。

但是，大部分程序員不善于寫文檔，自動(dòng)把注釋跑一下，就叫文檔啦？

流程的東西是根據(jù)實(shí)際情況來的嘛，想清楚要解決什么問題，想清楚各方需要什么最重要。

1、如果后端工程師對于整塊業(yè)務(wù)較為熟悉的話，并且前端經(jīng)驗(yàn)不是很足時(shí)，由后端產(chǎn)出接口文檔是較為合適的；
2、正常情況都是前后端溝通之后，前端需要什么數(shù)據(jù)，后端能提供什么，這樣商討之后再行產(chǎn)出接口文檔是較為合適的；

從我近年來的經(jīng)歷來看，讓后臺(tái)寫接口文檔好，當(dāng)然是前端基本沒有后臺(tái)經(jīng)驗(yàn)的前提下；
后臺(tái)寫的好處：
理由1:在前后臺(tái)開發(fā)人數(shù)差不多的時(shí)候，后臺(tái)的開發(fā)一般都要比前端開發(fā)快，讓他們?nèi)ヒ?guī)定接口和寫文檔，時(shí)間分配的相對合理；
理由2:前端自己命名，出現(xiàn)接口命名的不規(guī)范的幾率很大（一般接口的名字跟數(shù)據(jù)里表的名字比較接近），這樣容易造成重復(fù)返工，影響前后臺(tái)的工作效率；
理由3:作為一個(gè)前端的我，很樂意看接口文檔，不用自己費(fèi)腦細(xì)胞去想接口名字和形式；

前臺(tái)寫的好處：
理由1:（在不考慮后臺(tái)的書寫格式情況下）前端可以隨心地寫接口命名；
理由2:現(xiàn)在的前端都可以建假數(shù)據(jù)，可以把一些后臺(tái)的事給做了，這個(gè)時(shí)候后臺(tái)只要根據(jù)前端寫的接口去操作就好了，目前前端自己創(chuàng)建假數(shù)據(jù)的情況比較普遍；

一般的流程都是，后臺(tái)看ui設(shè)計(jì)稿，先搞數(shù)據(jù)庫需要那些字段，再去根據(jù)要求哪些請求寫對應(yīng)接口，再將接口文檔給前端，前端再實(shí)際需求將哪些后臺(tái)沒有的接口補(bǔ)上。

特殊情況：前端人數(shù)比后臺(tái)多，且前端具有后臺(tái)經(jīng)驗(yàn)。這樣讓他們?nèi)懡涌?，可以避免接口命名?guī)范問題同時(shí)也可以一次性將前端需要的接口告訴后臺(tái)，后臺(tái)也就不用重復(fù)去補(bǔ)遺漏的接口；

使用swagger自動(dòng)生成API文檔，還可以直接測試API的正確性。
如下：

好用、簡單、不扯皮

對這方面我的經(jīng)驗(yàn)也不多，我覺得主要看你們前后端的開發(fā)進(jìn)度，就以我自身管理的項(xiàng)目為例，來說說我的看法。

目前在做的項(xiàng)目是某知名旅游網(wǎng)站的一個(gè)小外包項(xiàng)目，采用前后端分離的開發(fā)模式，前端React+dva，后端基于SpringBoot框架提供Restful接口，項(xiàng)目周期短，時(shí)間緊，拿到需求之后，做出UI設(shè)計(jì)和數(shù)據(jù)庫設(shè)計(jì)，前端就開始干活了。在都沒有深入挖掘需求之前，前端在做某個(gè)功能點(diǎn)的時(shí)其實(shí)更清楚他需要什么接口，傳遞什么數(shù)據(jù)。所以我認(rèn)為這種情況下，前端提供接口需求是合理的。

至于產(chǎn)出接口文檔，我認(rèn)為這應(yīng)該是一個(gè)持續(xù)性而且易于維護(hù)的工作，我們用到了Swagger ui，后端通過一些注釋規(guī)則和簡單的配置就可以生成接口文檔，前端可以通過web端頁面實(shí)時(shí)的看到接口的變化，前端或者QA團(tuán)隊(duì)也可以通過web端頁面做接口在線測試，減少了溝通成本。而后端根據(jù)接口變化，只需要維護(hù)注釋，接口文檔就可以自動(dòng)生成并支持導(dǎo)出，減少了維護(hù)成本。

總體來說，我的做法是前端提供接口需求，后端生成接口文檔。

PS.剛注冊賬號(hào)，處女答送給你了，可能比較拙劣，但是希望對你有所啟發(fā)。

接口文檔是要必須要有的，現(xiàn)在前端開發(fā)可以自己使用假數(shù)據(jù)模擬出界面的各種情況，所以提前約定好接口格式之后，前端就可以通過模擬的方式獨(dú)立開發(fā)，而不需要等到后端接口開發(fā)完成之后才能進(jìn)行動(dòng)態(tài)網(wǎng)頁部分的開發(fā)。

接口文檔產(chǎn)出現(xiàn)在也可以自動(dòng)化了，我們團(tuán)隊(duì)現(xiàn)在用的是：swagger，后端可以在和前端約定好接口格式之后，定義好需要的接口之后，通過工具自動(dòng)生成。

接口格式的定義參考：RESTful API

另外還有一些接口管理平臺(tái)，可以用來管理接口，比如：

• RAP
• easy-mock
• apidoc

看具體項(xiàng)目。前端開發(fā)先空著需要接口的部分也行，畢竟連這段代碼不需要花多長時(shí)間，時(shí)間主要用在與開發(fā)人員聯(lián)調(diào)上。別人沒開發(fā)好，你也沒法聯(lián)調(diào)。
當(dāng)然好的方式是先定義好接口，形成文檔，大家都并行開發(fā)，按這個(gè)是理想化的情況，是擁有好的開發(fā)流程的公司，優(yōu)秀的開發(fā)團(tuán)隊(duì)及成員的前提下才能做到的。一些中小企業(yè)，特別是互聯(lián)網(wǎng)公司，需求，設(shè)計(jì)頻繁改動(dòng)很難做到API不改動(dòng)。

API可以用下Swagger， 自動(dòng)生成api文檔。 及時(shí)更新與聯(lián)調(diào)