新增pom依賴

<!--swagger2 start-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
<!--swagger2 end-->
 

Swagger2Config初始化配置：

package com.example.demo.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Auther: xiaojian
 * @Date: 2018/9/7 16:23
 * @Description:
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .groupName("demo")
                .select() // 選擇那些路徑和api會生成document
                .apis(RequestHandlerSelectors.any())// 對所有api進行監控
                //不顯示錯誤的介面地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//錯誤路徑不監控
                .paths(PathSelectors.regex("/.*"))// 對根下所有路徑進行監控
                .build();
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder().title("介面文件")
                .contact("xiaojian")
                .description("這是test API")
                .termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("v1.0")
                .build();
    }


}
 

Controller中測試方法：

在這裡我們使用@ApiOperation註解來宣告此方法為要生成的介面文件，在配置中已經配置過了，如果不想方法生成文件，不加此註解即可；

配置中已經使用了自定義的響應資訊，所以可以不設定@ApiResponses；

package com.example.demo.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

/**
 * @Auther: xiaojian
 * @Date: 2018/9/7 16:05
 * @Description:
 */
@RestController
@RequestMapping("/api")
@Api(description = "使用者介面測試")
public class test {

    @ApiOperation("測試方法")
    @RequestMapping(value = "/test",method = RequestMethod.GET)
    public String test(){
        return "hello world";
    }

    @ApiOperation("獲取使用者資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="使用者的姓名",defaultValue="zhaojigang"),
            @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="使用者的密碼",defaultValue="wangna")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="請求引數沒填好"),
            @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
    })
    @RequestMapping(value="/getUser",method=RequestMethod.POST)
    public Object getUser(@RequestHeader("username") String username, @RequestParam("password") String password){
        System.out.println("username = "+ username +", password = "+password);
        return "{'code:200','result:true'}";
    }
}
 

註解說明：

• @Api：用在類上，說明該類的作用
• @ApiOperation：用在方法上，說明方法的作用
• @ApiImplicitParams：用在方法上包含一組引數說明
• @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
  • paramType：引數放在哪個地方
    • header-->請求引數的獲取：@RequestHeader
    • query-->請求引數的獲取：@RequestParam
    • path（用於restful介面）-->請求引數的獲取：@PathVariable
    • body（不常用）
    • form（不常用）
  • name：引數名
  • dataType：引數型別
  • required：引數是否必須傳
  • value：引數的意思
  • defaultValue：引數的預設值
• @ApiResponses：用於表示一組響應
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
  • code：數字，例如400
  • message：資訊，例如"請求引數沒填好"
  • response：丟擲異常的類
• @ApiModel：描述一個Model的資訊（這種一般用在post建立的時候，使用@RequestBody這樣的場景，請求引數無法使用@ApiImplicitParam註解進行描述的時候）
  • @ApiModelProperty：描述一個model的屬性

以上這些就是最常用的幾個註解了。

需要注意的是：

• ApiImplicitParam這個註解不只是註解，還會影響執行期的程式，例子如下：

如果ApiImplicitParam中的phone的paramType是query的話，是無法注入到rest路徑中的，而且如果是path的話，是不需要配置ApiImplicitParam的，即使配置了，其中的value="手機號"也不會在swagger-ui展示出來。

啟動Spring Boot程式，訪問：http://localhost:8080/swagger-ui.html

生成文件效果：