SpringBoot集成Swagger2 以及漢化 快速教程

 

 

(一) Swagger介紹

               Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件

(二)為什么使用Swagger

                在現在的開發過程中還有很大一部分公司都是以口口相傳的方式來進行前后端的聯調，而接口文檔很大一部分都只停留在了說說而已的地步，很大一部分的原因就是”懶”，不想寫啊，寫了代碼再寫文檔，反正我是懶，只要不是強制性要求，沒人會願意寫這東西，而且在寫的過程中，一個字母的錯誤就會導致聯調時候的很大麻煩，但是通過Swagger，我們可以省略了這一步，而且文檔出錯率近乎於零，只要你在寫代碼的時候，稍加幾個注解，文檔自動生成。還有一點就是文檔的修改，定義好的接口並不是一成不變的，可能在開發過程中文檔修改不止一次的變化，這個時候就會很難受了，通過Swagger，在線自動生成你怎么寫他怎么生，方不方便你自己趕腳

 

(三)SpringBoot集成Swagger

       1) 添加依賴

<!--Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
 <!--Swagger-UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

     2) 創建配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.result.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger2構建api文檔")
                .description("Swagger的RESTful風格API")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0")
                .build();
    }

}

 

這些做好之后就已經集成了swagger-ui.html 

我們訪問

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

 

 

 

這樣其實我們已經配好了,但是怎么使用呢,其實我們只用幾個注解就能搞定

 

@Api()用於類；
表示標識這個類是swagger的資源

@ApiOperation()用於方法；
表示一個http請求的操作

@ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）

@ApiModel()用於類
表示對類進行說明，用於參數用實體類接收

@ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改

@ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略

@ApiImplicitParam() 用於方法
表示單獨的請求參數

 

例:

@RestController
@Api(value="用戶controller",tags={"用戶操作接口"})
public class UserController {


    @PostMapping("/login")
    @ApiOperation(value = "登錄", notes = "賬號密碼必輸")
    public ResponseResult login(String username,String password){
        if ("admin".equals(username) || "123456".equals(password)){
            User user = new User();
            user.setUsername(username);
            user.setPassword(password);
            user.setCity("中國");
            user.setSex("男");
            return new ResponseResult().setData(user);
        }else {
            return new ResponseResult("000000");
        }
    }

}

啟動之后:

 

 

(四)Swagger-UI的漢化

  對於上面我們所用的版 2.7.0，里面是含有國際化的(2.7.0以上版本不含國際化包)

  

 

   國際化的實現

             1) 在你的sources創建  META-INF/resources    ，在這個目錄下創建swagger-ui.html

             2) 找到你導入的springfox-swagger-ui  的包，找到這個html文件把里面的內容copy到你新建的swagger-ui.html

     

 

          3) 加入國際化的js

    <!-- 加入國際化的js -->
    <script src="webjars/springfox-swagger-ui/lang/translator.js" type="text/javascript"></script>
    <script src="webjars/springfox-swagger-ui/lang/zh-cn.js" type="text/javascript"></script>

 

重啟項目  漢化成功

 

 

對於swagger2.7.2以后的版本沒有包含國際化的內容，上述的方式是不行的，目前我還沒有找到對於新版本國際化的方案

 

如果誰有新版本國際化的方案請留言，謝謝