摘要：今天給你們帶來(lái)集成的教程。接口返回結(jié)果不明確。這些痛點(diǎn)在前后端分離的大型項(xiàng)目上顯得尤為煩躁。接口返回結(jié)果非常明確，包括數(shù)據(jù)類(lèi)型，狀態(tài)碼，錯(cuò)誤信息等。生成后的文件依賴(lài)如下這里使用的是的版本。另外，關(guān)注之后在發(fā)送可領(lǐng)取免費(fèi)學(xué)習(xí)資料。

微信公眾號(hào)：一個(gè)優(yōu)秀的廢人
如有問(wèn)題或建議，請(qǐng)后臺(tái)留言，我會(huì)盡力解決你的問(wèn)題。

快過(guò)年了，不知道你們啥時(shí)候放年假，忙不忙。反正我是挺閑的，所以有時(shí)間寫(xiě) blog。今天給你們帶來(lái) SpringBoot 集成 Swagger2 的教程。

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。

相信剛開(kāi)始不熟悉 web 開(kāi)發(fā)的時(shí)候，大家都有手寫(xiě) Api 文檔的時(shí)候。而手寫(xiě) Api 文檔主要有以下幾個(gè)痛點(diǎn)：

文檔需要更新的時(shí)候，需要再次發(fā)送一份給前端，也就是文檔更新交流不及時(shí)。

接口返回結(jié)果不明確。

不能直接在線測(cè)試接口，通常需要使用工具，比如 postman。

接口文檔太多，不好管理。

這些痛點(diǎn)在前后端分離的大型項(xiàng)目上顯得尤為煩躁。而 Swagger2 的出現(xiàn)恰好能個(gè)解決這些痛點(diǎn)。因?yàn)?Swagger2 有以下功能：

文檔自動(dòng)更新，只要生成 Api 的網(wǎng)址沒(méi)變，基本不需要跟前端溝通。

接口返回結(jié)果非常明確，包括數(shù)據(jù)類(lèi)型，狀態(tài)碼，錯(cuò)誤信息等。

可以直接在線測(cè)試文檔，而且還有實(shí)例提供給你。

只需要一次配置便可使用，之后只要會(huì)有一份接口文檔，非常易于管理。

首先新建一個(gè) SpringBoot 項(xiàng)目，還不會(huì)的參考我這篇舊文—— 如何使用 IDEA 構(gòu)建 Spring Boot 工程

構(gòu)建時(shí)，在選擇依賴(lài)那一步勾選 Web、LomBok、JPA 和 Mysql 依賴(lài)。其中 Mysql 可以不勾，因?yàn)槲疫@里用于操作實(shí)際的數(shù)據(jù)庫(kù)，所以我勾選了。

生成 SpringBoot 后的 Pom 文件依賴(lài)如下：這里使用的是 2.4.0 的 Swagger2 版本。

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.1.2.RELEASE
         
    
    com.nasus
    swagger2
    0.0.1-SNAPSHOT
    swagger2
    Demo project for Swagger2

    
        1.8
    

    
        
            org.springframework.boot
            spring-boot-starter-data-jpa
        

        
            org.springframework.boot
            spring-boot-starter-web
        

        
            mysql
            mysql-connector-java
            runtime
        

        
            org.springframework.boot
            spring-boot-starter-test
            test
        

        
            io.springfox
            springfox-swagger2
            2.4.0
        

        
            io.springfox
            springfox-swagger-ui
            2.4.0
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

第二步，在 SpringBoot 啟動(dòng)類(lèi)（Application）的同級(jí)目錄新建一個(gè) Swagger 配置類(lèi)，注意 Swagger2 配置類(lèi)必須與項(xiàng)目入口類(lèi) Application 位于同一級(jí)目錄，否則生成 Api 文檔失敗，代碼如下：

package com.nasus;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Project Name:swagger2-demo 

 * Package Name:com.nasus 

 * Date:2019/1/22 22:52 

 * Description: TODO: 描述該類(lèi)的作用 

 *
 * @author nasus

 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@Configuration
// 啟用 Swagger2
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 文檔信息對(duì)象
                .apiInfo(apiInfo())
                .select()
                // 被注解的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 標(biāo)題
                .title("springboot 利用 swagger 構(gòu)建 API 文檔")
                // Api 文檔描述
                .description("簡(jiǎn)單優(yōu)雅的 restful 風(fēng)格，https://blog.csdn.net/turodog/")

                .termsOfServiceUrl("https://blog.csdn.net/turodog/")
                // 文檔作者信息
                .contact(new Contact("陳志遠(yuǎn)", "https://github.com/turoDog", "turodog@foxmail.com"))
                // 文檔版本
                .version("1.0")
                .build();
    }
}

第三步，配置被注解的 Controller 類(lèi)，編寫(xiě)各個(gè)接口的請(qǐng)求參數(shù)，返回結(jié)果，接口描述等等，代碼如下：

package com.nasus.controller;

import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

/**
 * Project Name:swagger2-demo 

 * Package Name:com.nasus.controller 

 * Date:2019/1/22 22:07 

 * Description: TODO: 描述該類(lèi)的作用 

 *
 * @author nasus

 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@RestController
@RequestMapping("/student")
// @Api：修飾整個(gè)類(lèi)，描述Controller的作用
@Api("StudentController Api 接口文檔")
public class StudentController {

    @Autowired
    private StudentService studentService;

    // @ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口
    @ApiOperation(value="獲取所有學(xué)生列表", notes="獲取所有學(xué)生列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List getStudent() {
        List list = studentService.findAll();
        return list;
    }

    @ApiOperation(value="添加學(xué)生信息", notes="添加學(xué)生信息")
    // @ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
    @ApiImplicitParam(name = "student", value = "學(xué)生信息詳細(xì)實(shí)體", required = true, dataType = "Student")
    @PostMapping("/save")
    public Student save(@RequestBody Student student){
        return studentService.save(student);
    }

    @ApiOperation(value="獲學(xué)生信息", notes="根據(jù)url的id來(lái)獲取學(xué)生詳細(xì)信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
    @GetMapping("/{id}")
    public Student findById(@PathVariable("id") Integer id){
        return studentService.findById(id);
    }

    @ApiOperation(value="刪除學(xué)生", notes="根據(jù)url的id來(lái)指定刪除的學(xué)生")
    @ApiImplicitParam(name = "id", value = "學(xué)生ID", required = true, dataType = "Integer",paramType = "path")
    @DeleteMapping("/{id}")
    public String deleteById(@PathVariable("id") Integer id){
        studentService.delete(id);
        return "success";
    }

    @ApiOperation(value="更新學(xué)生信息", notes="根據(jù)url的id來(lái)指定更新學(xué)生信息")
    // @ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "學(xué)生ID", required = true, dataType = "Integer",paramType = "path"),
            @ApiImplicitParam(name = "student", value = "學(xué)生實(shí)體student", required = true, dataType = "Student")
    })
    @PutMapping(value="/{id}")
    public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
        Student oldStudent = this.findById(id);
        oldStudent.setId(student.getId());
        oldStudent.setName(student.getName());
        oldStudent.setAge(student.getAge());
        studentService.save(oldStudent);
        return "success";
    }

    // 使用該注解忽略這個(gè)API
    @ApiIgnore
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

第四步，啟動(dòng)項(xiàng)目，訪問(wèn) http://localhost:8080/swagger-ui.html 地址，結(jié)果如下圖：

github

@ApiOperation：用在方法上，說(shuō)明方法的作用
  1.value: 表示接口名稱(chēng)
  2.notes: 表示接口詳細(xì)描述 
@ApiImplicitParams：用在方法上包含一組參數(shù)說(shuō)明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面
  1.paramType：參數(shù)位置
  2.header 對(duì)應(yīng)注解：@RequestHeader
  3.query 對(duì)應(yīng)注解：@RequestParam
  4.path  對(duì)應(yīng)注解: @PathVariable
  5.body 對(duì)應(yīng)注解: @RequestBody
  6.name：參數(shù)名
  7.dataType：參數(shù)類(lèi)型
  8.required：參數(shù)是否必須傳
  9.value：參數(shù)的描述
  10.defaultValue：參數(shù)的默認(rèn)值
@ApiResponses：用于表示一組響應(yīng)
@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
  1.code：狀態(tài)碼
  2.message：返回自定義信息
  3.response：拋出異常的類(lèi)
@ApiIgnore: 表示該接口函數(shù)不對(duì)swagger2開(kāi)放展示
@Api：修飾整個(gè)類(lèi)，描述Controller的作用
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息

@ApiImplicitParam 注解下的 paramType 屬性,會(huì)影響接口的測(cè)試,如果設(shè)置的屬性跟spring 的注解對(duì)應(yīng)不上,會(huì)獲取不到參數(shù),例如 paramType=path ,函數(shù)內(nèi)卻使用@RequestParam 注解,這樣,可能會(huì)獲取不到傳遞進(jìn)來(lái)的參數(shù),需要按照上面進(jìn)行對(duì)應(yīng),將 @RequestParam 注解改為 @PathVariable 才能獲取到對(duì)應(yīng)的參數(shù)。

以上就是我對(duì) Swagger2 的理解與使用，以上只是教大家入門(mén) Swagger2 ，想要深入使用還是希望自行查閱官方文檔。最后，對(duì) Python 、Java 感興趣請(qǐng)長(zhǎng)按二維碼關(guān)注一波，我會(huì)努力帶給你們價(jià)值，如果覺(jué)得本文對(duì)你哪怕有一丁點(diǎn)幫助，請(qǐng)幫忙點(diǎn)好看，讓更多人知道。

另外，關(guān)注之后在發(fā)送 1024 可領(lǐng)取免費(fèi)學(xué)習(xí)資料。資料內(nèi)容詳情請(qǐng)看這篇舊文：Python、C++、Java、Linux、Go、前端、算法資料分享