Spring boot集成swagger2生成接口文档的全过程
作者:jstarseven 时间:2021-07-29 14:28:07
一、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界面显示
来源:https://www.cnblogs.com/jstarseven/p/11509884.html
标签:springboot,集成,swagger2
0
投稿
猜你喜欢
Android编程基于自定义View实现绚丽的圆形进度条功能示例
2023-07-24 17:13:26
springboot 自定义异常并捕获异常返给前端的实现代码
2022-07-23 03:09:52
SpringBoot @NotBlank错误的解决方案
2023-01-12 20:05:59
Spring Boot中的Properties的使用详解
2021-07-02 07:25:22
java:程序包org.springframework.boot不存在的完美解决方法
2023-09-03 20:37:32
如何使用Spring自定义Xml标签
2022-11-14 19:01:08
java调用Restful接口的三种方法
2021-09-07 16:49:04
详解安装Eclipse Maven插件的几种方法
2022-06-01 06:15:20
SpringBoot中的HATEOAS详情
2022-12-27 03:12:31
手动编译C#代码的方法
2021-05-27 05:42:40
java保证对象在内存中唯一性的实现方法
2023-11-27 21:30:03
Spring与Mybatis基于注解整合Redis的方法
2022-09-19 09:19:56
C# Aspose.Words 删除word中的图片操作
2023-07-29 12:01:43
Android 在程序运行时申请权限的实例讲解
2023-08-04 17:35:57
C#使⽤XmlReader和XmlWriter操作XML⽂件
2023-12-13 10:25:00
SpringBoot整合Redis将对象写入redis的实现
2023-07-30 14:39:07
搭建MyBatis-Plus框架并进行数据库增删改查功能
2023-11-09 04:33:43
Java使用DOM4j实现读写XML文件的属性和元素
2021-10-19 00:21:52
Java编程实现对象克隆(复制)代码详解
2023-02-13 10:12:31
C#计时器的三种实现方法
2023-06-08 04:41:32