springboot集成swagger2

介紹：

       Swagger是全球最大的OpenAPI規範（OAS）API開發工具框架，支持從設計和文檔到測試和部署的整個API生命周期的開發。（摘自Swagger官網）Swagger說白了就是幫助開發者省去了維護介面文檔的時間，用來調試介面非常方便。

一、創建項目

      在上一篇博客中介紹了怎麼創建springboot項目，在這篇博客中就不過多講，在博客的最後我會上傳項目的源碼，愛學習的小伙伴們可以下載交流，有問題的小伙伴可以在博客下方留言，博主看到後第一時間會給你回覆。

二、引入swagger2依賴

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

三、創建Swagger2配置類

package com.chaoqi.springboot_swagger.dao.utils;

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;

//讓Spring來載入該類配置
@Configuration
//開啟Swagger2
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("HelloWorld")
                .apiInfo(apiInfo())
                .select()
                // 掃描的包所在位置
                .apis(RequestHandlerSelectors.basePackage("com.chaoqi.springboot_swagger.web"))
                // 掃描的 URL 規則
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        // 聯繫信息
        return new ApiInfoBuilder()
                // 大標題
                .title("")
                // 描述
                .description("")
                // 服務條款 URL
                .termsOfServiceUrl("")
                // 版本
                .version("")
                .build();
    }
}

創建controller

 Swagger2註解說明：

@Api：用在請求的類上，表示對類的說明
    tags="說明該類的作用，可以在UI界面上看到的註解"
    value="該參數沒什麼意義，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用
    value="說明方法的用途、作用"
    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組參數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用於restful介面）--> 請求參數的獲取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：參數類型，預設String，其它值dataType="Integer"       
        defaultValue：參數的預設值

@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
        code：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類

@ApiModel：用於響應類上，表示一個返迴響應數據的信息
            （這種一般用在post創建的時候，使用@RequestBody這樣的場景，
            請求參數無法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性

package com.chaoqi.springboot_swagger.web;

import com.chaoqi.springboot_swagger.dao.domain.MusicInfo;
import com.chaoqi.springboot_swagger.service.MusicInfoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(value = "/music")
@Api(tags = "音樂信息")
public class MusicInfoController {

    @Autowired
    private MusicInfoService musicInfoService;

    @ApiOperation(value = "根據Id獲取歌手信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", dataType = "Long"),
    })
    @RequestMapping(value = "/showMusic", method = RequestMethod.GET)
    public List<MusicInfo> getMusicInfo(@RequestParam(name = "id", required = false) Long id) {
        List<MusicInfo> musicInfo1 = musicInfoService.getMusicInfo(id);
        return musicInfo1;
    }

    @ApiOperation(value="根據Id刪除歌手信息")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", dataType = "Long")
    @RequestMapping(value="/deleteMusic", method=RequestMethod.DELETE)
    public Long deleteUser(@RequestParam(name = "id", required = false) Long id) {
        Long sum = musicInfoService.getDeleteId(id);
        return sum;
    }
}

 啟動項目運行http://localhost:8080/swagger-ui.html

整合成功，源碼下載地址：https://github.com/caicahoqi/ChaoqiIsPrivateLibrary