1.Swagger是什麼？

官方說法：Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

個人覺得，swagger的一個最大的優點是能實時同步api與文件。在專案開發過程中，發生過多次：修改程式碼但是沒有更新文件，前端還是按照老舊的文件進行開發，在聯調過程中才發現問題的情況（當然依據開閉原則，對介面的修改是不允許的，但是在專案不穩定階段，這種情況很難避免）。

2.Spring Boot整合Swagger2

一、引入依賴：

http://mvnrepository.com中搜索springFox，引入Swagger2和Swagger Ui的依賴：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
 

            <version>2.7.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId
 
>
            <version>2.7.0</version>
        </dependency>

二、啟動類DemoApplication加入@EnableSwagger2註解

@SpringBootApplication
@RestController
@EnableSwagger2
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @GetMapping("/hello")
    public String hello(){
        return "hello spring security";
    }
}

三、注入資源配置檔案（UI檢視的配置）

@Configuration
@EnableSwagger2
public class WebConfig extends WebMvcConfigurerAdapter{

    /**
     * 這個地方要重新注入一下資原始檔，不然不會注入資源的，也沒有注入requestHandlerMappping,相當於xml配置的
     *  <!--swagger資源配置-->
     *  <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
     *  <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
     *  不知道為什麼，這也是spring boot的一個缺點（菜鳥覺得的）
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars*")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

四、啟動服務，訪問 localhost:8080/swagger-ui.html 即可看到服務的api文件

五、可加入@ApiModelProperty註解更方便前端開發人員理解傳入引數為物件的屬性（註解加在實體類的屬性中）

public class UserQueryCondition {

    private String username;

    @ApiModelProperty(value = "使用者年齡起始值")
    private int age;

    @ApiModelProperty(value = "使用者年齡終止值")
    private int ageTo;

    private String xxx;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public int getAgeTo() {
        return ageTo;
    }

    public void setAgeTo(int ageTo) {
        this.ageTo = ageTo;
    }

    public String getXxx() {
        return xxx;
    }

    public void setXxx(String xxx) {
        this.xxx = xxx;
    }
}

六、可加入@ApiOperation註解讓前端開發人員理解發送http請求對應的Controller方法的功能（註解加在Controller方法上）

    @GetMapping
    @JsonView(User.UserSimpleView.class)
    @ApiOperation(value = "使用者查詢服務")
    public List<User> query(UserQueryCondition condition,@PageableDefault(page=2,size=17,sort="username,asc") Pageable pageable){//用spring自帶的pageable物件來得到分頁資訊
        System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.MULTI_LINE_STYLE));
        System.out.println(pageable.getPageSize());
        System.out.println(pageable.getPageNumber());
        System.out.println(pageable.getSort());
        List<User> users = new ArrayList<>();
        users.add(new User());
        users.add(new User());
        users.add(new User());
        return users;
    }

七、可加入@ApiParam註解讓前端開發人員理解傳入的一般請求引數（如String型別）的功能（註解加在Controller方法的傳入引數上）

    @GetMapping("/{id:\\d+}")
    @JsonView(User.UserDetailView.class)
    public User getInfo(@ApiParam("使用者id") @PathVariable String id){
        //throw new UserNotExistException(id);
        System.out.println("進入getInfo服務");
        User user = new User();
        user.setUsername("tom");
        return user;
    }

八、檢視文件註解的效果