Spring boot集成swagger2如何生成接口文檔

小編給大家分享一下Spring boot集成swagger2如何生成接口文檔，希望大家閱讀完這篇文章之后都有所收獲，下面讓我們一起去探討吧！

一、Swagger介紹

Swagger是一個規范和完整的框架，用于生成、描述、調用和可視化RESTful風格的web服務。目標是使客戶端和文件系統作為服務器以同樣的速度來更新文件的方法，參數和模型緊密集成到服務器。這個解釋簡單點來講就是說，swagger是一款可以根據restful風格生成的接口開發文檔，并且支持做測試的一款中間軟件。

二、使用swagger優勢

1、對于后端開發人員來說

• 不用再手寫Wiki接口拼大量參數，避免手寫錯誤

• 對代碼侵入性低，采用全注解的方式，開發簡單

• 方法參數名修改、新增、減少參數都可以直接生效，不用手動維護

• 缺點：增加了開發成本，寫接口還得再寫一套參數配置

2、對前端開發來說

• 后端只需要定義好接口，會自動生成文檔，接口功能、參數一目了然

• 聯調方便，如果出了問題，直接測試接口，實時檢查參數和返回值，就可以快速定位是前端還是后端的問題

3、對于測試來說

• 但對于測試沒有前端界面UI的功能，可以直接用它來測試接口

• 操作簡單，不用了解具體代碼就可以操作 

三、springboot集成swagger使用

1、新建maven項目（結構如下：）

2、配置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.1.3.RELEASE</version>
    <relativePath/>
  </parent>
  <groupId>com.dds.sbswagger</groupId>
  <artifactId>sb-swagger</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>sb-swagger</name>
  <description>Demo project for Spring Boot</description>

  <properties>
    <java.version>1.8</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <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>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <version>1.18.6</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

3、程序啟動類

package com.dds.sbswagger;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author dds
 */
@SpringBootApplication
@Slf4j
public class SbSwaggerApplication {

  public static void main(String[] args) {
    SpringApplication.run(SbSwaggerApplication.class, args);
    log.info("\n----------------------------------------------------------\n\t" +
        "Application demo is running! Access URLs:\n\t" +
        "swagger-ui: \thttp://127.0.0.1:8080/swagger-ui.html\n\t" +
        "----------------------------------------------------------");
  }

}

4、SwaggerConfig配置類

package com.dds.sbswagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.Collections;

/**
 * @author DDS
 * @date 2019/9/10 13:55
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dds.sbswagger.controller"))
        //加了ApiOperation注解的類，才生成接口文檔
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.any())
        .build()
        .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfo(
        "Spring Boot項目集成Swagger實例文檔",
        "我的微信公眾號：大道七哥，歡迎大家關注。",
        "API V1.0",
        "Terms of service",
        new Contact("大道七哥", "https://www.cnblogs.com/jstarseven/", "jstarseven@163.com"),
        "Apache", "http://www.apache.org/", Collections.emptyList());
  }
}

5、實體類model

package com.dds.sbswagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author DDS
 * @date 2019/9/10 13:55
 */
@ApiModel("用戶實體")
@Data
public class User {

  /**
   * 用戶Id
   */
  @ApiModelProperty("用戶id")
  private int id;

  /**
   * 用戶名
   */
  @ApiModelProperty(value = "用戶姓名", example = "zhangdan", required = true)
  private String name;

  /**
   * 用戶地址
   */
  @ApiModelProperty(value = "用戶地址", example = "北京市海淀區", required = true)
  private String address;

  /**
   * 用戶手機號
   */
  @ApiModelProperty(value = "用戶手機號", example = "15689652367", required = true)
  private String phone;

  /**
   * 用戶年齡
   */
  @ApiModelProperty(value = "用戶年齡", example = "24", required = true)
  private Integer age;

}

6、接口開發

package com.dds.sbswagger.controller;

import com.dds.sbswagger.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

/**
 * @author DDS
 * @date 2019/9/10 13:55
 */
@RestController
@RequestMapping("/user")
@Api(tags = "用戶相關接口", description = "提供用戶相關的Rest API")
public class UserController {

  @PostMapping("/add")
  @ApiOperation(value = "新增用戶接口", notes = "手機號、密碼都是必輸項，年齡隨邊填，但必須是數字")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "name", value = "用戶名稱", required = true, paramType = "form"),
      @ApiImplicitParam(name = "address", value = "用戶地址", required = true, paramType = "form"),
      @ApiImplicitParam(name = "phone", value = "用戶手機號", required = true, paramType = "form"),
      @ApiImplicitParam(name = "age", value = "用戶年齡", required = true, paramType = "form", dataType = "Integer")
  })
  public boolean addUser(@RequestBody User user) {
    return false;
  }

  @ApiOperation("通過id查找用戶接口")
  @GetMapping("/find/{id}")
  public User findById(@PathVariable("id") int id) {
    return new User();
  }

  @ApiOperation("更新用戶信息接口")
  @PutMapping("/update")
  @ApiResponses({
      @ApiResponse(code = 400, message = "請求參數沒填好"),
      @ApiResponse(code = 404, message = "請求路徑沒有或頁面跳轉路徑不對"),
      @ApiResponse(code = 405, message = "未知錯誤")
  })
  public boolean update(@RequestBody User user) {
    return true;
  }

  @ApiOperation("刪除用戶接口")
  @DeleteMapping("/delete/{id}")
  public boolean delete(@PathVariable("id") int id) {
    return true;
  }
}

7、swagger界面顯示

看完了這篇文章，相信你對“Spring boot集成swagger2如何生成接口文檔”有了一定的了解，如果想了解更多相關知識，歡迎關注億速云行業資訊頻道，感謝各位的閱讀！