swagger使用總結

時間 2019-12-05

標籤 swagger 使用總結简体版

原文原文鏈接

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

先看一個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.htmljava

自此一個很是方便又簡單的swagger-ui集成好了，寫完業務邏輯代碼能夠立馬公佈restful api給前端調用。git

具體使用

基於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/…)。github

@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這個項目。spring

搞明白swagger，springfox是什麼

swagger

Swagger 是一款目前世界最流行的API管理工具，是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。文檔提供了一個方法，咱們能夠用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了好比 names、order 等 API 信息。你能夠經過一個文本編輯器來編輯 Swagger 文件，或者你也能夠從你的代碼註釋中自動生成。各類工具均可以使用 Swagger 文件來生成互動的 API 文檔。你須要具體閱讀這裏What Is Swagger?來理解。api

Swagger擁有衆多不一樣語言和平臺的開源實現與工具，他有不少實現方式，很是方便，而且支持語言特別多，詳細請查看（必定要看一眼，就知道他有多強大）Tools and Integrations。安全