Springboot集成swagger2生成接口文档
2024-08-27 15:49:32
原文出处:http://www.yund.tech/zdetail.html?type=1&id=89322e28b75270c682abc576595967d4
作者:jstarseven
Swagger介绍
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件。
使用swagger优势
1、对于后端开发人员来说
- 不用再手写Wiki接口拼大量参数,避免手写错误
- 对代码侵入性低,采用全注解的方式,开发简单
- 方法参数名修改、新增、减少参数都可以直接生效,不用手动维护
- 缺点:增加了开发成本,写接口还得再写一套参数配置
2、对前端开发来说
- 后端只需要定义好接口,会自动生成文档,接口功能、参数一目了然
- 联调方便,如果出了问题,直接测试接口,实时检查参数和返回值,就可以快速定位是前端还是后端的问题
3、对于测试来说
- 但对于测试没有前端界面UI的功能,可以直接用它来测试接口
- 操作简单,不用了解具体代码就可以操作
Springboot集成swagger使用
新建maven项目
配置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>
程序启动类
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" +
"----------------------------------------------------------");
} }
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());
}
}
实体类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; }
接口开发
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;
}
}
swagger界面显示
-END-
最新文章
- java 自动登录代码
- pacman -Syu : key could not be looked up remotely.
- VFP MSSOAPTOOKIT 使用SOAP Headers
- Rabbitmq实现负载均衡与消息持久化
- asp.net如何将DataSet转换成josn并输出
- angular2 学习笔记 ( Router 路由 )
- apache的ab进行页面的压力测试
- 【留坑】uva12299
- 正则表达式中/i,/g,/m的作用
- python之路-SQLAlchemy
- 玩转Web之Jsp(三)-----Jsp+SQLServer 用sql语句实现分页
- ios发布笔录
- C# 经典入门12章-使用泛型-1
- Selenium里可以自行封装与get_attribute对应的set_attribute方法
- vi/vim下tab的长度修改
- 微信小程序入门八头像上传
- 时间模块 --- time
- 包装类、object、单例模式、final、抽象类
- TCP连接管理(TCP Connection Management)
- pyhton新手学习之增删改查
热门文章
- Altium Designer16设置GND和VCC线宽规则的一种操作方法及注意事项
- Kalman Filter、Extended Kalman Filter以及Unscented Kalman Filter介绍
- 通过Blazor使用C#开发SPA单页面应用程序(2)
- pythonday04数据类型(二)
- Tomcat源码分析 (五)----- Tomcat 类加载器
- 深入解析Mysql中事务的四大隔离级别及其所解决的读现象
- MYSQL 入门配置
- Java Socket:飞鸽传书的网络套接字
- MYSQL--表与表之间的关系、修改表的相关操作
- net core 3.0 之Grpc新特性小试牛刀