Spring boot集成swagger2生成接口文档的全过程

更新时间：2019年09月12日 09:55:46 作者：jstarseven

这篇文章主要给大家介绍了关于Spring boot集成swagger2生成接口文档的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用Spring boot具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧

一、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界面显示

总结

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，谢谢大家对脚本之家的支持。

您可能感兴趣的文章:

java实现String类型和Date类型相互转换
很多人表示,java将string类型转为date类型不知道应该怎样做,本文就来介绍一下java实现String类型和Date类型相互转换,具有一定的参考价值,感兴趣的可以了解一下
2023-10-10
@GrpcServise 注解的作用和使用示例详解
@GrpcService 是一个 Spring Boot 处理器，它会查找实现了 grpc::BindableService 接口的类，并将其包装成一个 Spring Bean 对象，这篇文章主要介绍了@GrpcServise 注解的作用和使用,需要的朋友可以参考下
2023-05-05
关于报错IDEA Terminated with exit code
如果在IDEA构建项目时遇到下面这样的报错IDEA Terminated with exit code 1，那必然是Maven的设置参数重置了，导致下载错误引起的，本文给大家分享两种解决方法，需要的朋友可以参考下
2022-08-08
Java使用Arrays.sort()方法实现给对象排序
这篇文章主要介绍了Java使用Arrays.sort()方法实现给对象排序，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-12-12
idea mybatis配置log4j打印sql语句的示例
本篇文章主要介绍了idea mybatis配置log4j打印sql语句的示例，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2018-01-01
Java动态获取实现某个接口下所有的实现类对象集合
今天小编就为大家分享一篇关于Java动态获取实现某个接口下所有的实现类对象集合，小编觉得内容挺不错的，现在分享给大家，具有很好的参考价值，需要的朋友一起跟随小编来看看吧
2018-12-12
PowerJob的OmsLogHandler工作流程源码解析
这篇文章主要为大家介绍了PowerJob的OmsLogHandler工作流程源码解析，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-12-12
Java高并发BlockingQueue重要的实现类详解
这篇文章主要给大家介绍了关于Java高并发BlockingQueue重要的实现类的相关资料，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2021-01-01
Java实现读取和写入properties文件
这篇文章主要介绍了Java实现读取和写入properties文件方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2023-08-08
JavaWeb使用POI操作Excel文件实例
这篇文章主要介绍了JavaWeb使用POI操作Excel文件,需要的朋友可以参考下
2017-04-04

Spring boot集成swagger2生成接口文档的全过程

相关文章

最新评论

大家感兴趣的内容

最近更新的内容

常用在线小工具