專案中你可能已經使用到了swagger，或許你並沒有對它過於留意，比如說springfox、swagger-springmvc、swagger-ui他們之間的關係是什麼，springfox原理是什麼。

先看一個pull下來就能啟動的spring-boot，swagger-ui整合demo

git專案地址 github.com/moxingwang/…

獲取程式碼

git pull https://github.com/moxingwang/swagger.git
複製程式碼

啟動

cd swagger
mvn spring-boot:run
複製程式碼

訪問

http://localhost:8080/sw/swagger-ui.html

自此一個非常方便又簡單的swagger-ui整合好了，寫完業務邏輯程式碼可以立馬公佈restful api給前端呼叫。

具體使用

基於springfox使用swagger非常簡單，只需要maven依賴以及少量config配置就可以實現，上面的demo中都有體現，或者直接訪問springfox的github上面的demospringfox/springfox-demos 。
springfox更詳細配置請參考官方文件Springfox Reference Documentation。
swagger annotation具體使用 Swagger-Core Annotations，這裡面有詳細的annotation描述。

特別注意事項

雖然說swagger是個好東西，但是使用中切不可以忽略的一個問題--【安全】。dev uat1環境中你可以開放swagger給前端或者測試，千萬不要把它開放給了生產，如果你的swagger ui不小心放到了生產，那是一件多麼可怕的事情，真可以來個‘一鍋端’，切記切記。官網文件有相關的安全配置springfox.github.io/springfox/d…。也可以在不同環境配置中新增要給變數來控制，swagger ui是否可用(github.com/moxingwang/…)。

    @Value("${swagger.switch}")
    private boolean swaggerSwitch;

    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        if (swaggerSwitch) {
            docket.enable(true);
        } else {
            docket.enable(false);
        }

        docket.apiInfo(apiInfo()).select().paths(PathSelectors.any()).build();

        return docket;
    }
複製程式碼

其他

如若你在spring-boot中使用swagger還嫌麻煩，想要直接一個註解搞定，建議你看SpringForAll/spring-boot-starter-swagger這個專案。

搞明白swagger，springfox是什麼

swagger

Swagger 是一款目前世界最流行的API管理工具，是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。文件提供了一個方法，我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 資訊。你可以通過一個文字編輯器來編輯 Swagger 檔案，或者你也可以從你的程式碼註釋中自動生成。各種工具都可以使用 Swagger 檔案來生成互動的 API 文件。你需要具體閱讀這裡What Is Swagger?來理解。

Swagger擁有眾多不同語言和平臺的開源實現與工具，他有很多實現方式，非常方便，並且支援語言特別多，詳細請檢視（一定要看一眼，就知道他有多強大）Tools and Integrations。

這裡也可以參考Swagger Annotation 詳解（建議收藏）這篇文章檢視相關幾個元件的中文介紹。

springfox

springfox是java對swagger的一個具體實現。springfox的前身是swagger-springmvc，用於springmvc與swagger的整合。它內部會自動解析Spring容器中Controller暴露出的介面，並且也提供了一個介面用於展示或呼叫這些API。

要分分鐘瞭解springfox的原理，請參考阿里雲社群API管理工具Swagger介紹及Springfox原理分析這篇文章。

最後再來看一篇文章Swagger 和 Springfox-Swagger 的關係，加深你對Swagger和Springfox-Swagger的理解。

總結

如果你後臺開發，提供restful介面給前端。建議你使用swagger-ui提供restful的介面文件描述。
如果你是介面設計者，建議你使用Swagger Editor設計。
如果你是介面呼叫方，想快速生成介面呼叫程式碼，很簡單，你只需要使用Swagger Editor生存client程式碼就行了，十分方便。

swagger使用總結