SpringBoot整合Swagger

一、Swagger介紹

Swagger是一個RESTful API的工具，目标是為REST API定義一個标準的、與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下，能發現和了解各種服務的功能。通過Swagger可以獲得項目的一種互動式文檔，用戶端SDK的自動生成等功能。

Swagger是一個簡單但功能強大的API表達工具。它具有地球上最大的API工具生态系統，數以千計的開發人員，使用幾乎所有的現代程式設計語言，都在支援和使用Swagger。使用Swagger生成API，可以得到互動式文檔，自動生成代碼的SDK以及API的發現特性等。Swagger已經是世界上最流行的API表達工具。

使用Spring Boot內建Swagger的理念是，使用注解标記出需要在API文檔中展示的資訊，Swagger會根據項目中标記的注解來生成對應的API文檔。

二、Spring Boot內建Swagger

Spring Boot 內建 Swagger 2.X 很簡單，需要引入依賴并做基礎配置即可，下面我們來感受一下。

A、相關依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

B、配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //  swagger通路位址http://localhost:端口号/程式上下文/swagger-ui.html
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為目前包路徑
                .apis(RequestHandlerSelectors.basePackage("org.school.examination.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //建構 api文檔的詳細資訊函數,注意這裡的注解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面标題
                .title("線上考試系統")
                //建立人
                .contact(new Contact("教育", "http://blog.csdn.net/m0_37876631", "[email protected]"))
                //版本号
                .version("1.0")
                //描述
                .description("接口資訊")
                .build();
    }

}

@EnableSwagger2，表示此項目啟用Swagger API文檔。

在啟動時初始化，傳回執行個體Docket（Swagger API摘要），需要指定掃描的包路徑，隻有此路徑下的Controller類才會自動生成Swagger API文檔。

C、在Controller層增加相關注解

@RestController
@Api(value = "學科資訊相關接口", tags = "學科資訊相關接口")
public class SubjectController {

    private Logger logger = LoggerFactory.getLogger(SubjectController.class);

    @Autowired
    private SubjectService subjectService;

    @GetMapping(value = "/getSubject.do")
    @ApiOperation(value = "擷取學科資訊", notes = "擷取學科資訊")
    public String getSubject() {
        ......
    }

    @PostMapping(value = "/saveSubject.do")
    @ApiOperation(value = "儲存學科資訊", notes = "儲存學科資訊")
    public String saveSubject(@RequestBody SubjectEntity entity) {
        ......
    }
}

配置完成之後啟動項目，通路http://localhost:8088/examination/swagger-ui.html，即可看到Swagger的UI效果。