SpringBoot整合Swagger2(Demo示例)

時間  2019-11-09
標籤 springboot 整合 swagger2 swagger demo 示例 欄目 Spring 简体版
原文   原文鏈接

寫在前面

因爲公司項目採用先後端分離，維護接口文檔基本上是必不可少的工做。一個理想的狀態是設計好後，接口文檔發給前端和後端，大夥按照既定的規則各自開發，開發好了對接上了就能夠上線了。固然這是一種很是理想的狀態，而手寫文檔雖然能夠解決一些問題，可是也存在如下痛點。html

手寫Api文檔的幾個痛點：前端

  1. 文檔須要更新的時候，須要再次發送一份給前端，也就是文檔更新交流不及時。
  2. 接口返回結果不明確
  3. 不能直接在線測試接口，一般須要使用工具，好比postman
  4. 接口文檔太多，很差管理

還好，有一些工具能夠減輕咱們的工做量，Swagger2 就是其中之一。java

本文以Demo示例展現一下在Spring Boot 中如何整合 Swagger2 。mysql

Swagger2經常使用註解說明

swagger經過註解代表該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。web

@Api：               修飾整個類，描述Controller的做用
@ApiOperation：      描述一個類的一個方法，或者說一個接口
@ApiParam：          單個參數描述
@ApiModel：          用對象來接收參數
@ApiProperty：       用對象接收參數時，描述對象的一個字段
@ApiResponse：       HTTP響應其中1個描述
@ApiResponses：      HTTP響應總體描述
@ApiIgnore：         使用該註解忽略這個API
@ApiError ：         發生錯誤返回的信息
@ApiImplicitParam：  一個請求參數
@ApiImplicitParams： 多個請求參數
具體說明以下：

@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：用在屬性上，描述響應類的屬性

SpringBoot整合Swagger2進行CRUD操做

數據準備：

數據庫名：springboottest，表名：ss_companyspring

建表語句：sql

DROP TABLE IF EXISTS ss_company;
CREATE TABLE ss_company (
  id varchar(40) NOT NULL COMMENT 'ID',
  name varchar(255) DEFAULT NULL COMMENT '公司名稱',
  expiration_date datetime DEFAULT NULL COMMENT '到期時間',
  address varchar(255) DEFAULT NULL COMMENT '公司地址',
  license_id varchar(255) DEFAULT NULL COMMENT '營業執照-圖片',
  representative varchar(255) DEFAULT NULL COMMENT '法人表明',
  phone varchar(255) DEFAULT NULL COMMENT '公司電話',
  company_size varchar(255) DEFAULT NULL COMMENT '公司規模',
  industry varchar(255) DEFAULT NULL COMMENT '所屬行業',
  remarks varchar(255) DEFAULT NULL COMMENT '備註',
  state int(2) DEFAULT '1' COMMENT '狀態',
  balance double DEFAULT NULL COMMENT '當前餘額',
  city varchar(20) DEFAULT NULL,
  PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

數據插入語句：數據庫

INSERT INTO ss_company VALUES ('1', '字節跳動', null, '北京', 'xxx002', '張某', '123', '10000人以上', '互聯網', '互聯網公司', '1', '100', '北京');
INSERT INTO ss_company VALUES ('2', '百度', null, '北京市海淀區', 'bzd001', '李某', '110', '5000-10000人', '計算機', '', '1', '100', '北京');
INSERT INTO ss_company VALUES ('3', '阿里巴巴', null, '中國杭州市濱江區', 'bzd002', '馬某', '110', '5000-10000人', '電子商務', '', '1', '100', '杭州');
INSERT INTO ss_company VALUES ('4', '騰訊', null, '深圳市南山區', 'bzd003', '馬某', '110', '5000-10000人', '遊戲', '', '1', '100', '深圳');

 

1>  建立SpringBoot工程，導入pom文件依賴

 application.yml配置：
spring:
  datasource:
    driver-class-name: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/springboottest?characterEncoding=utf-8
    username: root
    password: root

server:
  port: 8090

      pom依賴：

<dependencies>
        <!-- SpringBoot 啓動器 web依賴 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </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>

        <!--jdbc-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <!--springboot支持的是jpa,mybatisplus本身作了啓動器-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.2.0</version>
        </dependency>
        <!--mysql-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>5.1.47</version>
        </dependency>
        <!-- lombok插件依賴 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- SpringBoot測試啓動依賴 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

2>  建立pojo實體類

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

import java.io.Serializable;
import java.util.Date;

@Data
@TableName("ss_company")
public class Company implements Serializable {
    /**
     * AUTO : AUTO(0, 「數據庫ID自增」),
     * INPUT : INPUT(1, 「用戶輸入ID」),
     * ID_WORKER : ID_WORKER(2, 「全局惟一ID」),默認值若是不設置會在用該策略
     * UUID : UUID(3, 「全局惟一ID」),
     * NONE : NONE(4, 「該類型爲未設置主鍵類型」),
     * ID_WORKER_STR : ID_WORKER_STR(5, 「字符串全局惟一ID」);
     */
    @TableId(type = IdType.UUID)
    private String id;

    private String name;

    private Date expirationDate;

    private String address;

    private String licenseId;

    private String representative;

    private String phone;

    private String companySize;

    private String industry;

    private String remarks;

    private Integer state;

    private Double balance;

    private String city;

    private static final long serialVersionUID = 1L;
} 

3>  建立Result類(建議)

備註：Result類主要是在測試的時候，給出提示信息後端

import java.io.Serializable;

public class Result implements Serializable {

    private boolean success;   //狀態判斷
    private String message;    //返回的消息內容

    public Result(boolean success,String message) {
        this.message = message;
        this.success = success;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }
}

4>  建立Dao接口

備註：因爲com.baomidou.mybatisplus.core.mapper包已經封裝了CRUD功能，因此這裏的Dao接口只需繼承對應的BaseMapper<Company>接口就能夠了api

import com.baomidou.mybatisplus.core.mapper.BaseMapper;

public interface CompanyDao extends BaseMapper<Company> {
}

5>  建立Service接口

import java.util.List;

public interface CompanyService {
    //查詢全部
    List<Company> findAll();

    //單一查詢
    Company findOne(String id);

    //更新
    void update(Company company);

    //添加
    void add(Company company);

    //刪除
    void delete(String id);
}

6>  建立ServiceImpl實現類

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class CompanyServiceImpl implements CompanyService {
    @Autowired
    private CompanyDao companyDao;

    @Override
    public List<Company> findAll() {
        return companyDao.selectList(null);
    }

    @Override
    public Company findOne(String id) {
        return companyDao.selectById(id);
    }

    @Override
    public void update(Company company) {
        companyDao.updateById(company);
    }

    @Override
    public void add(Company company) {
        companyDao.insert(company);
    }

    @Override
    public void delete(String id) {
        companyDao.deleteById(id);
    }
}

7>   建立Controller類

import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Api("Swagger示例CRUD操做")
@RestController
@RequestMapping("/company")
public class CompanyController {
    @Autowired
    private CompanyService companyService;

    //查詢全部
    @ApiOperation("獲取公司列表")
    @GetMapping
    public List<Company> findAll(){
        return companyService.findAll();
    }

    //查詢單一
    @ApiOperation(value = "根據id獲取公司信息",notes = "id必須是數字")
    @ApiImplicitParams({@ApiImplicitParam(name = "id",value = "id",required = true,paramType = "path")})
    @ApiResponses({@ApiResponse(code=400,message="id爲空")})
    @GetMapping("/{id}")
    public Company findById(@PathVariable("id") String id){
        return companyService.findOne(id);
    }

    //添加
    @ApiOperation("新增公司信息")
    @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company")
    @PostMapping
    public Result add(@RequestBody Company company){
        try {
            companyService.add(company);
            return new Result(true,"新增成功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"新增失敗");
        }
    }

    //修改
    @ApiOperation("修改公司信息")
    @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company")
    @PutMapping
    public Result update(@RequestBody Company company){
        try {
            companyService.update(company);
            return new Result(true,"修改爲功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"修改失敗");
        }
    }

    //刪除
    @ApiOperation("刪除用戶")
    @ApiImplicitParam(name = "id", value = "單個用戶信息", dataType = "String")
    @DeleteMapping("/{id}")
    public Result delete(@PathVariable("id") String id){
        try {
            companyService.delete(id);
            return new Result(true,"刪除成功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"刪除失敗");
        }
    }
}

8>  建立Controller類

import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Api(tags = "Swagger示例CRUD操做")
@RestController
@RequestMapping("/company")
public class CompanyController {
    @Autowired
    private CompanyService companyService;

    //查詢全部
    @ApiOperation("獲取公司列表")
    @GetMapping
    public List<Company> findAll(){
        return companyService.findAll();
    }

    //查詢單一
    @ApiOperation(value = "根據id獲取公司信息",notes = "id必須是數字")
    @ApiImplicitParams({@ApiImplicitParam(name = "id",value = "id",required = true,paramType = "path")})
    @ApiResponses({@ApiResponse(code=400,message="id爲空")})
    @GetMapping("/{id}")
    public Company findById(@PathVariable("id") String id){
        return companyService.findOne(id);
    }

    //添加
    @ApiOperation("新增公司信息")
    @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company")
    @PostMapping
    public Result add(@RequestBody Company company){
        try {
            companyService.add(company);
            return new Result(true,"新增成功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"新增失敗");
        }
    }

    //修改
    @ApiOperation("修改公司信息")
    @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company")
    @PutMapping
    public Result update(@RequestBody Company company){
        try {
            companyService.update(company);
            return new Result(true,"修改爲功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"修改失敗");
        }
    }

    //刪除
    @ApiOperation("刪除用戶")
    @ApiImplicitParam(name = "id", value = "單個用戶信息", dataType = "String")
    @DeleteMapping("/{id}")
    public Result delete(@PathVariable("id") String id){
        try {
            companyService.delete(id);
            return new Result(true,"刪除成功");
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(false,"刪除失敗");
        }
    }
}

9>  建立Swagger2配置類

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 SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(restApiInfo())
                .select()
                // 指定包名
                .apis(RequestHandlerSelectors.basePackage("com.darren.springbootswaggerdemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo restApiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger2構建api文檔")
                .description("簡單優雅的restful風格")
                .termsOfServiceUrl("no terms of serviceUrl")
                .version("1.0")
                .build();
    }
}

備註說明：

 

 

這裏提供的配置類，首先經過 @EnableSwagger2 註解啓用 Swagger2 ，而後配置一個 Docket Bean，這個 Bean 中，配置映射路徑和要掃描的接口的位置，

在 apiInfo 中，主要配置一下 Swagger2 文檔網站的信息，例如網站的 title，網站的描述，聯繫人信息，使用的協議，版本信息，許可證信息等等。

至此，SpringBoot整合Swagger2示例Demo已配置完成，下面啓動SpringBoot啓動類測試，而後打開瀏覽器，在地址欄中輸入：

http://localhost:8090/swagger-ui.html

可以看到以下界面，說明配置已成功

 

 

 

 

 能夠看到，全部的接口這裏都列出來了，包括接口請求方式，接口地址以及接口的名字等，點開一個接口，能夠看到以下信息，

點擊右上角的 Try it out，就能夠進行接口測試：

 

 

 點擊 Execute 按鈕，表示發送請求進行測試。測試結果會展現在下面的 Response 中。

 

 

 

 除此以外，其餘的功能測試，還有一些響應值的註解，你們也均可以本身摸索下。

 

至此，SpringBoot整合Swagger2示例已完成，又能夠浪一會啦。。。。。。。。。。。。。。。。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程