Swagger集成Springboot

1.Swagger介紹

1.1.什麼是Swagger

Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。

1.2.優勢

支持 API 自動生成同步的在線文檔：使用 Swagger 後可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節約寫文檔的時間去學習新技術。
提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值即可在線測試接口。

2.Swagger使用

2.1.在pom.xml文件中添加第三方swagger依賴

        <!--swagger jar start-->
        <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>
        <!--swagger jar end-->

2.1.2項目完整pom

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <mybatis.starter.version>1.3.2</mybatis.starter.version>
        <mapper.starter.version>2.0.2</mapper.starter.version>
        <mysql.version>5.1.32</mysql.version>
        <durid.starter.version>1.1.10</durid.starter.version>
    </properties>

    <dependencies>
        <!-- SpringBoot整合SpringMVC的啓動器 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- SpringBoot整合jdbc和事務的啓動器 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <!-- mybatis啓動器 -->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>${mybatis.starter.version}</version>
        </dependency>
        <!-- 通用Mapper啓動器 -->
        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>${mapper.starter.version}</version>
        </dependency>
        <!-- mysql驅動 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>${mysql.version}</version>
        </dependency>
        <!-- Druid連接池 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${durid.starter.version}</version>
        </dependency>
       <!--swagger jar start-->
        <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>
        <!--swagger jar end-->
</dependencies>

2.2.yml配置

#Tomcat
server:
  port: 9090
#DB configuration
spring:
  application:
    name: web-service
  datasource:
    url: jdbc:mysql://localhost:3306/work?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.jdbc.Driver

2.3.在Spring Boot項目的啓動類上添加@EnableSwagger2，啓動Swagger

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class OneweekApplication {

    public static void main(String[] args) {
        SpringApplication.run(OneweekApplication.class, args);
    }

}

2.4.添加配置類

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;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                //自己的controller路徑
                apis(RequestHandlerSelectors.basePackage("com.capgemini.controller")). 
                paths(PathSelectors.any()).
                build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().
                title("springboot利用swagger構建api文檔").
                description("用戶的CRUD").
                version("1.0").
                build();
    }
}

2.5.User實體類

package com.capgemini.domain;

import com.fasterxml.jackson.annotation.JsonFormat;
import org.springframework.format.annotation.DateTimeFormat;

import java.util.Date;
import javax.persistence.*;

@Table(name = "`user`")
public class User {
    @Id
    @Column(name = "id")
    @GeneratedValue(generator = "JDBC")
    private Integer id;

    @Column(name = "username")
    private String username;

    @Column(name = "age")
    private Integer age;

    @Column(name = "sex")
    private String sex;

    @Column(name = "birthday")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    private Date birthday;

    @Column(name = "phone")
    private String phone;
    @Transient
    private String sencode;
    @Transient
    private String code;

    public String getSencode() {
        return sencode;
    }

    public void setSencode(String sencode) {
        this.sencode = sencode;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    /**
     * @return id
     */
    public Integer getId() {
        return id;
    }

    /**
     * @param id
     */
    public void setId(Integer id) {
        this.id = id;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    /**
     * @return username
     */
    public String getUsername() {
        return username;
    }

    /**
     * @param username
     */
    public void setUsername(String username) {
        this.username = username;
    }

    /**
     * @return age
     */
    public Integer getAge() {
        return age;
    }

    /**
     * @param age
     */
    public void setAge(Integer age) {
        this.age = age;
    }

    /**
     * @return sex
     */
    public String getSex() {
        return sex;
    }

    /**
     * @param sex
     */
    public void setSex(String sex) {
        this.sex = sex;
    }

    /**
     * @return birthday
     */
    public Date getBirthday() {
        return birthday;
    }

    /**
     * @param birthday
     */
    public void setBirthday(Date birthday) {
        this.birthday = birthday;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append(getClass().getSimpleName());
        sb.append(" [");
        sb.append("Hash = ").append(hashCode());
        sb.append(", id=").append(id);
        sb.append(", username=").append(username);
        sb.append(", age=").append(age);
        sb.append(", sex=").append(sex);
        sb.append(", birthday=").append(birthday);
        sb.append(", phone=").append(phone);
        sb.append(", sencode=").append(sencode);
        sb.append(", code=").append(code);
        sb.append("]");
        return sb.toString();
    }
}

2.6.Mapper類(使用的通用mapper)

package com.capgemini.dao;

import com.capgemini.domain.User;
import tk.mybatis.mapper.common.Mapper;

@org.apache.ibatis.annotations.Mapper
public interface UserMapper extends Mapper<User> {
}

2.7.Service類

package com.capgemini.service;
import com.capgemini.domain.User;

public interface UserService {

    //添加數據
    void addUser(User user);

}

2.8.Service實現類

package com.capgemini.service.impl;

import com.capgemini.domain.User;
import org.springframework.stereotype.Service;

import javax.annotation.Resource;

import com.capgemini.dao.UserMapper;
import com.capgemini.service.UserService;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional
public class UserServiceImpl implements UserService {

    @Resource
    private UserMapper userMapper;

    //添加用戶
    @Override
    public void addUser(User user) {
        userMapper.insert(user);
    }

}

2.9.Controller類

package com.capgemini.controller;

import com.capgemini.domain.MyException;
import com.capgemini.domain.User;
import com.capgemini.service.UserService;
import com.capgemini.util.CommonUtil;
import com.capgemini.vo.BaseResult;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;

//@Api 描述類  接口的主要用途
//@ApiOperation  描述方法用途
//@ApiImplicitParam  描述方法的參數
//@ApiImplicitParams  描述方法的參數(Multi-Params)
//@ApiIgnore 忽略某類/方法/參數的文檔

@RestController
@RequestMapping("/user")
public class UserController {
    @Resource
    private UserService userService;

    //添加用戶
    @ApiOperation(value = "創建用戶", notes = "根據User對象創建用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    @PostMapping
    public ResponseEntity<BaseResult> addUser(@RequestBody User user) {
        BaseResult br = null;
        try {
            userService.addUser(user);
            br = new BaseResult(CommonUtil.SUCCESS, "添加成功");
        } catch (Exception e) {
            br = new BaseResult(CommonUtil.FAIL, "添加失敗");
        }
        return new ResponseEntity<>(br, HttpStatus.OK);
    }
}

3.訪問

http://localhost:9090/swagger-ui.html#/