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之後的版本沒有包含國際化的內容，上述的方式是不行的，目前我尚未找到對於新版本國際化的方案

 

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