前言

隨著互聯(lián)網(wǎng)的技術(shù)的發(fā)展谚中，前后端分離對于開發(fā)人員來說毋庸置疑是一個好的發(fā)展。
前端人員只負(fù)責(zé)前端界面又跛，后端人員也只負(fù)責(zé)后端業(yè)務(wù)邏輯處理嗦董。但是在團(tuán)隊開發(fā)中，總總避免不了前端人員和后端人員缺少溝通情況下峡眶，難免會在接口文檔上出現(xiàn)錯誤剧防。
就是在這種情況下，swagger 就是為了這種情況而出現(xiàn)的辫樱。通過后端swagger提供的方法注釋寫接口文檔诵姜，生成頁面文檔。再讓前端人員測試接口搏熄。
在網(wǎng)上資料學(xué)習(xí)的過程中棚唆，了解到swagger是一種規(guī)范，是用于Spring基礎(chǔ)上的一種規(guī)范實現(xiàn)心例。
也是為Spring提供了服務(wù)宵凌。

1.Swagger2的好處

Swagger2作為一個規(guī)范和完整的框架，可以用于生成止后、描述瞎惫、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)溜腐。
-接口文檔在線生成，文檔實時為業(yè)務(wù)需求變動瓜喇，節(jié)省維護(hù)成本
-支持在線接口測試
-便于保存挺益、整理、查閱和調(diào)試API接口

2.基于Springboot 整合swagger2

2.1 swagger2 注解使用示例

controller 類里面@注解

• @Api：用在請求的類上乘寒，說明該類的作用

@Api：用在請求的類上望众，說明該類的作用
    tags="說明該類的作用"
    value="該參數(shù)沒什么意義，所以不需要配置"

-@ApiOperation：用在請求的方法上伞辛，說明方法的作用

@ApiOperation："用在請求的方法上烂翰，說明方法的作用"
    value="說明方法的作用"
    notes="方法的備注說明"

-@ApiImplicitParam: 用在請求的方法上,一個參數(shù)說明
-@ApiImplicitParams：用在請求的方法上，包含一組參數(shù)說明

@ApiImplicitParams：用在請求的方法上蚤氏，表示一組參數(shù)說明
@ApiImplicitParam：用在@ApiImplicitParams注解中甘耿，指定一個請求參數(shù)的各個方面
name：參數(shù)名
value：參數(shù)的漢字說明、解釋
required：參數(shù)是否必須傳
paramType：參數(shù)放在哪個地方
· header --> 請求參數(shù)的獲雀捅酢：@RequestHeader
· query --> 請求參數(shù)的獲燃烟瘛：@RequestParam
· path（用于restful接口）--> 請求參數(shù)的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：參數(shù)類型于游，默認(rèn)String殿怜，其它值dataType="Integer"
defaultValue：參數(shù)的默認(rèn)值

controller演示上面幾個@注解

@Api(tags = "預(yù)約業(yè)務(wù)處理控制類")
@RestController
@RequestMapping("/appoint")
public class AppointController {

    @Autowired
    private AppointmentMapper appointmentMapper;

     /**
     * 查詢預(yù)約id
     * @param appointId
     * @return
     */
    @ApiOperation(value = "獲取預(yù)約信息",notes = "根據(jù)url的appointId來獲取預(yù)約信息")
    @ApiImplicitParam(name = "appointId",value = "預(yù)約id",dataType = "String",paramType = "path")
    @RequestMapping(value = "/getByAppoint/{appointId}",method = RequestMethod.GET)
    public ResultVo getByAppointById(@PathVariable(value = "appointId")
                                     String appointId){
        Appointment appointment = appointmentMapper.selectByPrimaryKey(appointId);
        return ResultVoUtil.success(appointment);
    }


    /**
     * 添加信息
     * @param appointment
     * @return
     */
    @ApiOperation(value = "添加預(yù)約信息",notes = "注意格式參數(shù)")
    @ApiImplicitParam(paramType = "body")
    @RequestMapping(value = "/add",method = RequestMethod.POST)
    public ResultVo Add( Appointment appointment){
        int i = appointmentMapper.insert(appointment);
        if (i > 0 ){
            return ResultVoUtil.success();
        }
        return null;
    }

    /**
     * 刪除預(yù)約
     * @param appointId
     * @return
     */
    @ApiOperation(value ="刪除預(yù)約信息",notes = "根據(jù)url的appointId帶來刪除預(yù)約信息")
    @ApiImplicitParam(name = "appointId",value = "預(yù)約id",dataType = "String",paramType = "path")
    @RequestMapping(value = "/deleteByAppoint/{appointId}",method = RequestMethod.DELETE)
    public ResultVo deleteByProductId(@PathVariable(value = "appointId")
                                                  String appointId){


        int i =  appointmentMapper.deleteByPrimaryKey(appointId);
        if (i > 0 ){
           return ResultVoUtil.success();
        }
        return null;
    }

    /**
     * 修改預(yù)約
     * @param appointment
     * @return
     */
    @ApiOperation(value = "修改預(yù)約信息",notes = "注意格式參數(shù)")
    @ApiImplicitParam(paramType = "body")
    @RequestMapping(value = "/update",method = RequestMethod.PUT)
    public ResultVo Update( Appointment appointment){
        int i = appointmentMapper.updateByPrimaryKey(appointment);
        if (i > 0 ){
        return     ResultVoUtil.success();
        }
        return null;
    }
 
// 用于演示 ApiImplicitParams  本方法不屬于本controller,可以把它注釋掉
  @ApiOperation(value = "添加用戶",notes = "注冊格式參數(shù)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "nickname",value = "用戶賬號",required = true,dataType = "String"),
            @ApiImplicitParam(name = "openId",value = "用戶密碼",required = true,dataType = "String")
    })
    @RequestMapping(value = "/login",method = RequestMethod.POST)
    public ResultVo login(String openId,String nickname ){
        WeChatUser weChatUser = new WeChatUser();
        weChatUser.setOpenId(openId);
        weChatUser.setNickName(nickname);
        WeChatUser select = userMapper.selectOne(weChatUser);
        return ResultVoUtil.success();      
    }
}

實體類@注解

-@ApiModel：用于響應(yīng)類上，表示一個返回響應(yīng)數(shù)據(jù)的信息

@ApiModel：用于響應(yīng)類上曙砂，表示一個返回響應(yīng)數(shù)據(jù)的信息
            （這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景骏掀，
            請求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時候）
    @ApiModelProperty：用在屬性上鸠澈，描述響應(yīng)類的屬性

演示

@Data
@Accessors(chain = true)
@Table(name = "appoint_ment")
@ApiModel(value = "appointmentInfo",description = "用于預(yù)約服務(wù)模塊")
public class Appointment implements Serializable {
    
    @Id
    @KeySql(useGeneratedKeys = true) //回顯
    private String appointId;

    /**名字*/
    @ApiModelProperty(name = "appointName",value = "預(yù)約服務(wù)名",required = true)
    private String appointName;

    /**日期*/
    @ApiModelProperty(name = "appointWeek",value = "預(yù)約星期",required = true)
    private Date appointWeek;

    /**時間 08:00*/
    @ApiModelProperty(name = "appointTime",value = "預(yù)約時間",required = true)
    private String appointTime;

    /**單價*/
    @ApiModelProperty(name = "appointPrice",value = "服務(wù)價格",required = true)
    private BigDecimal appointPrice;

    /** 狀態(tài)，0正常 1下架*/
    @ApiModelProperty(name = "appointStatus",value = "服務(wù)狀態(tài): 0-正常 1-偽刪除")
    private Integer appointStatus;

    /**類目編號*/
    @ApiModelProperty(name = "categoryType",value = "服務(wù)類型",required = true)
    private Integer categoryType;
    
    private Date createTime;

    private Date updateTime;
    
}

2.2 maven pom.xml依賴

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.1.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com,mi</groupId>
    <artifactId>springboot-swagger-demo-1</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>

    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>

        <!--通用mapper-->
        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>2.0.2</version>
        </dependency>

        <!--MySQL依賴 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- swagger2  主要的兩個依賴包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>
</project>

-swagger2 主要的兩個依賴包

springfox-swagger2和springfox-swagger-ui

2.3 application.yml 配置文件

spring:
  datasource:
    driver-class-name: com.mysql.jdbc.Driver
    username: root
    password: 123456
    url: jdbc:mysql://localhost/haircut?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC
  mvc:
    static-path-pattern: /**
mybatis:
  mapper-locations: classpath:mapper/*Mapper.xml
  type-aliases-package: com.mi.domain
server:
  servlet:
    context-path: /swagger
  port: 8090

2.4 mapper通用接口

在這里演示2個mapper接口
-預(yù)約表

/**
 * @author : Rong
 * @date : 2019/2/12
 * @Desc: 預(yù)約表
 */
public interface AppointmentMapper extends Mapper<Appointment> {
}

2.5 封裝返回數(shù)據(jù)類

@Data
public class ResultVo<T> {

    /**錯誤碼*/
    private Integer code;

    /**提示信息*/
    private String msg ;

    /**具體內(nèi)容*/
    private T data;
}

2.6 封裝返回數(shù)據(jù)工具類

public class ResultVoUtil {
    
    public static ResultVo success(Object object){
        ResultVo resultVo = new ResultVo();
        resultVo.setData(object);
        resultVo.setCode(0);
        resultVo.setMsg("成功");
        return resultVo;
    }

    public static ResultVo success(){
        return success(null);
    }

    public static ResultVo error(Integer code, String msg){
        ResultVo resultVo = new ResultVo();

        resultVo.setCode(code);
        resultVo.setMsg(msg);
        return resultVo;
    }
}

2.7 創(chuàng)建swagger2 配置啟動類

@Configuration
public class swaggerConfiguration {
    @Bean
    public Docket createDocketApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mi"))
                .paths(PathSelectors.any())
                .build();
    }

    //  API 信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("xxxx服務(wù)文檔")
                .description("XXX API 接口文檔")
                .version("1.0")
                .build();
    }
}

-Docket : 是用來生成文檔的函數(shù)截驮，其下有包含該調(diào)用的方法
-apiInfo：是用來描述文檔的基本信息
-select：用來控制哪些接口暴露給 Swagger 來展現(xiàn)
-apis: 會掃描該包下所有的定義controller的API
-paths： 任何url請求文檔

3. 啟動項目

SpringBoot 啟動成功后笑陈，訪問 http://localhost:8090/swagger/swagger-ui.html

3.1 swagger-ui 界面

image.png

從上面圖片可以看到swagger配置類生成的文檔名稱

3.2 展開方法請求

image.png

展開開后可以看到接口列表，頁面會列出該類中定義的所有接口葵袭。點擊任意接口涵妥，可查看該接口的 url 路徑、請求類型坡锡、參數(shù)描述和返回碼說明等信息蓬网。

點擊右上角的 “Try it out！”按鈕鹉勒，錄入請求信息帆锋，可以測試接口請求調(diào)用！

4.swagger2 注解類型基本介紹

-@Api：修飾整個類禽额，描述Controller的作用
-@ApiOperation：描述一個類的一個方法锯厢，或者說一個接口
-@ApiParam：單個參數(shù)描述
-@ApiModel：用對象來接收參數(shù)
-@ApiProperty：用對象接收參數(shù)時皮官，描述對象的一個字段
-@ApiResponse：HTTP響應(yīng)其中1個描述
-@ApiResponses：HTTP響應(yīng)整體描述
-@ApiIgnore：使用該注解忽略這個API
-@ApiError ：發(fā)生錯誤返回的信息
-@ApiImplicitParam：描述一個請求參數(shù)，可以配置參數(shù)的中文含義实辑，還可以給參數(shù)設(shè)置默認(rèn)值
-@ApiImplicitParams：描述由多個 @ApiImplicitParam 注解的參數(shù)組成的請求參數(shù)列表

有興趣的同學(xué)可以去了解其它注解的用途捺氢。

項目github地址源碼：https://github.com/mi499938150/springboot-swagger-demo