swagger快速入門

本篇只介紹快速入門，想要深入學習請看swagger官方文檔和源碼！

1．學習目標

1.瞭解swagger的作用和概念

2.瞭解前後端分離

3.在springboot中集成swagger

2．swagger的由來

1.現在流行的前後端分離技術：Vue+Springboot

2.後端時代：前端只用管理靜態頁面 html ->後端。模板引擎 jsp，thymeleaf 後端是主力。

3.前後端分離時代：

後端：後端控制層，服務層，數據訪問層【後端團隊】

前端：前端控制層，視圖層【前端團隊】

前端可以僞造後端數據 json

前後端如何交互？ ---à通過API接口交互

4.前後端分離的好處：前後端相對獨立，松耦合；前後端甚至可以部署在不同的服務器上。

5.隨之而來便產生一個問題：前後端集成聯調，前端人員和後端人員無法做到及時協商，儘早解決，最終導致問題集中爆發。

解決方案：

制定一個schema（計劃），實時更新最新的api，降低集成的風險。

早先年，制定word文檔。

後來出現了前後端分離：

早期，前端測試後端接口：postman

現在，後端提供接口：需要實時更新最新的消息及改動。這時候，swagger就應運而生了！

3. swagger

號稱世界上最流行的api框架；

Restful api文檔在線自動生成工具->Api文檔與Api定義同步更新；

直接運行，可以在線測試api接口；

支持多種語言（java，php…）

官網：https://swagger.io/

4. springboot集成swagger

需要springfox-swagger2 , springfox-swagger-ui

springboot集成swagger:

步驟：

1.新建一個springboot的web項目。

2.導入相關依賴

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

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.9.2</version>

</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.9.2</version>

</dependency>

3.編寫一個hello world工程

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class HelloController {

    @ResponseBody
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

}

4.配置swagger -> config （沒有配置，只是開啓了swagger2默認配置）

@Configuration

@EnableSwagger2 //開啓swagger2

public class SwaggerCfg {

    

}

5.測試運行

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

訪問成功的界面應該如下：

5．swagger配置

swagger的bean實例docket

修改swagger信息，改爲自己寫的內容

package com.example.demo.config;



import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;



import java.util.ArrayList;



@Configuration

@EnableSwagger2 //開啓swagger2

public class SwaggerCfg {

    public static final Contact DEFAULT_CONTACT = new Contact("夜空", "", "");

    //配置swagger的docket的bean實例

    @Bean

    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo());

    }

    //配置swagger信息 apiInfo

    private ApiInfo apiInfo(){

        return new ApiInfo("夜空的swagger配置筆記",

                "哈哈哈",

                "1.0", "urn:tos",

                DEFAULT_CONTACT, "Apache 2.0",

                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());

    }





}

我們發現界面的swagger信息變成了我們配置的自定義內容。

這些配置信息基本上沒有什麼用，唯一有用的就是接口信息和描述。

6. swagger配置掃描接口

默認的掃描接口是將所有的的接口全部掃描。我們也可以自定義掃描哪些接口。

一般情況用默認即可，這裏爲了學習，我們瞭解一下swagger如何配置掃描接口。

主要基於--docket::select()方法—

select下包括了兩種方法：

1.apis() ---選擇掃描包的方式

2.paths() ---過濾，過濾什麼路徑，添加之後將無法掃描到該包下的接口。

指定要掃描的包：

@Bean

public Docket docket(){

    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //RequestHandlerSelectors配置要掃描接口的方式，basePackage指定掃描的包

            .build();

}

這裏只說了最常用的一種方法，basePackage指定掃描的包，還有其他的掃描方式可以進入源碼閱讀和實驗。

對於paths，我們也做一個實驗:

public Docket docket(){

    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            //RequestHandlerSelectors配置要掃描接口的方式,basePackage指定掃描的包

            .select()

            .paths(PathSelectors.ant("com.example.demo.controller"))

            //.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))

            .build();

}

這時候，因爲我們過濾了com.example.demo.controller，該包下的所有接口都掃描不到，結果也驗證了這一點！

配置是否啓動swagger

還是再docket裏，docket::enable 設爲false即可。

最後留一個問題，我只希望我的swagger在生產環境中使用，在發佈的時候不使用，應該如何做。網上有很多相關資料，這裏就不做解答啦。

配置分組：

配置分組也很簡單，在docket下有一個groupName方法，可以設置分組，這裏就不詳細說了。docket裏還有其他的方法，大家多研究docket的代碼就可以。

@Bean

public Docket docket(){

    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .groupName("yekong")  //配置分組

            .select()

            .paths(PathSelectors.ant("com.example.demo.controller"))

            //.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))

            .build();

}

我們看下效果，發現分組名變成我們設置的分組。

如果是多人寫代碼，每個人可以各給自己設置一個分組，這樣每個人寫的接口都會被分開管理，不會相互影響。做法就是在配置文件中每個人都寫一份自己的docket實例，然後設置分組即可。這樣就可以做到協同開發了！

@Bean

public Docket docket1(){

    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .groupName("yekong")

            .select()

            .paths(PathSelectors.ant("xxx"))

            .build();

}


@Bean

public Docket docket2(){

    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .groupName("xiaohei")

            .select()

            .paths(PathSelectors.ant("xxx"))

            .apis(RequestHandlerSelectors.basePackage("xxx"))

            .build();

}

7. 實體類配置

在controller中，只要我們的接口返回值存在實體類，它就會被掃描到swagger中。

@PostMapping("/user")

public User user(){

    return new User();

}

swagger快速入門