技术栈分享之----Swagger

embedded/2025/3/17 22:44:02/

一:swagger介绍

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。

为了简化swagger的使用,Spring框架对swagger进行了整合,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成描述文件,进而生成与代码一致的接口文档和客户端代码。

Springfox对应的maven坐标如下:

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>

二:swagger常用API介绍

注解说明
@Api用在请求的类上,例如Controller,表示对类的说明
@ApiModel用在类上,通常是实体类,表示一个返回响应数据的信息
@ApiModelProperty用在属性上,描述响应类的属性
@ApiOperation用在请求的方法上,说明方法的用途、作用
@ApiImplicitParams用在请求的方法上,表示一组参数说明
@ApiImplicitParam用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

三:swagger案例 

第一步:创建maven工程swagger_demo并配置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 https://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.2.2.RELEASE</version><relativePath/></parent><groupId>cn.itcast</groupId><artifactId>swagger_demo</artifactId><version>0.0.1-SNAPSHOT</version><name>swagger_demo</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>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency></dependencies>
</project>

第二步:创建application.yml文件

server:port: 9000

第三步: 创建实体类User和Menu

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(description = "用户实体")
public class User {@ApiModelProperty(value = "主键")private int id;@ApiModelProperty(value = "姓名")private String name;@ApiModelProperty(value = "年龄")private int age;@ApiModelProperty(value = "地址")private String address;
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(description = "菜单实体")
public class Menu {@ApiModelProperty(value = "主键")private int id;@ApiModelProperty(value = "菜单名称")private String name;
}

第四步:创建UserController和MenuController

import cn.itcast.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;@RestController
@RequestMapping("/user")
@Api(tags = "用户控制器")
public class UserController {@GetMapping("/getUsers")@ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")public List<User> getAllUsers(){User user = new User();user.setId(100);user.setName("itcast");user.setAge(20);user.setAddress("bj");List<User> list = new ArrayList<>();list.add(user);return list;}@PostMapping("/save")@ApiOperation(value = "新增用户", notes = "新增用户信息")public String save(@RequestBody User user){return "OK";}@PutMapping("/update")@ApiOperation(value = "修改用户", notes = "修改用户信息")public String update(@RequestBody User user){return "OK";}@DeleteMapping("/delete")@ApiOperation(value = "删除用户", notes = "删除用户信息")public String delete(int id){return "OK";}@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"),@ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"),})@ApiOperation(value = "分页查询用户信息")@GetMapping(value = "page/{pageNum}/{pageSize}")public String findByPage(@PathVariable Integer pageNum,@PathVariable Integer pageSize) {return "OK";}
}

 

import cn.itcast.entity.Menu;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;@RestController
@RequestMapping("/menu")
@Api(tags = "菜单控制器")
public class MenuController {@GetMapping("/getMenus")@ApiOperation(value = "查询所有菜单", notes = "查询所有菜单信息")public List<Menu> getMenus(){Menu menu = new Menu();menu.setId(100);menu.setName("itcast");List<Menu> list = new ArrayList<>();list.add(menu);return list;}@PostMapping("/save")@ApiOperation(value = "新增菜单", notes = "新增菜单信息")public String save(@RequestBody Menu menu){return "OK";}@PutMapping("/update")@ApiOperation(value = "修改菜单", notes = "修改菜单信息")public String update(@RequestBody Menu menu){return "OK";}@DeleteMapping("/delete")@ApiOperation(value = "删除菜单", notes = "删除菜单信息")public String delete(int id){return "OK";}@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"),@ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"),})@ApiOperation(value = "分页查询菜单信息")@GetMapping(value = "page/{pageNum}/{pageSize}")public String findByPage(@PathVariable Integer pageNum,@PathVariable Integer pageSize) {return "OK";}
}

 第五步:创建配置类SwaggerAutoConfiguration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {@Beanpublic Docket createRestApi1() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("用户接口组").select()//为当前包路径.apis(RequestHandlerSelectors.basePackage("cn.itcast.controller.user")).build();return docket;}@Beanpublic Docket createRestApi2() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("菜单接口组").select()//为当前包路径.apis(RequestHandlerSelectors.basePackage("cn.itcast.controller.menu")).build();return docket;}//构建 api文档的详细信息private ApiInfo apiInfo() {return new ApiInfoBuilder()//页面标题.title("API接口文档")//创建人.contact(new Contact("dlwlrma晴子", "http://www.dlwlrma.com", ""))//版本号.version("1.0")//描述.description("API 描述").build();}
}

 第六步:创建启动类SwaggerDemoApplication

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class SwaggerDemoApplication {public static void main(String[] args) {SpringApplication.run(SwaggerDemoApplication.class, args);}
}

执行启动类main方法启动项目,访问地址:http://localhost:9000/swagger-ui.html  


http://www.ppmy.cn/embedded/173442.html

相关文章

html设置浮动

标准文档流 标准文档流&#xff1a;指元素根据块元素或行内元素的特性按从上到下&#xff0c;从左到右的方式自然排列。这也是元素默认的排列方式 标准文档流组成 块级元素&#xff08;block&#xff09; <h1>…<h6>、<p>、<div>、列表 块级元素&a…

c++介绍函数指针 十

指针代表内存中地址标识符&#xff0c;变量&#xff0c;数组都是存储内存中的数据。所以可以获得它们的地址&#xff0c;用指针来表示这块内存。 如图输出内存中的地址。 对于一个函数来说&#xff0c;也是内存中存储这段数据&#xff0c;所以我们也可以获取函数的地址。 函数…

FFmpeg处理流程

结构体 AVFormatContext 作用&#xff1a;管理媒体文件的封装格式上下文&#xff0c;存储文件格式、流信息、I/O 操作等元数据。 关键字段 AVInputFormat *iformat; // 输入格式&#xff08;如MP4、FLV&#xff09; AVStream **streams; // 音视频流数组 int nb_str…

AI 游戏的创新与挑战都有哪些?

一、AI 游戏的创新 &#xff08;一&#xff09;技术突破 AI 技术的不断进步为游戏产业带来了新的机遇。深度学习、强化学习等技术的应用&#xff0c;使得游戏中的 AI 角色能够展现出更加智能的行为和决策能力。例如&#xff0c;通过强化学习&#xff0c;AI 可以在游戏中自主学…

3ds Max 鼠标与快捷键组合操作指南

以下是 3ds Max 鼠标与快捷键组合操作指南&#xff0c;按功能分类整理&#xff0c;涵盖 视图控制、对象操作、建模工具 等核心场景。自用记录&#xff0c;不喜勿喷。 一、视图控制&#xff08;鼠标核心操作&#xff09; 操作快捷键鼠标动作功能说明平移视图鼠标中键拖动按住中…

PCDN 与边缘计算的结合​

在数字化时代&#xff0c;PCDN 与边缘计算作为两项前沿技术&#xff0c;正悄然改变着网络生态格局。PCDN&#xff0c;即点到点内容分发网络&#xff0c;它借助众多用户的闲置带宽与计算资源&#xff0c;构建起庞大的分布式网络&#xff0c;能有效提升内容传输效率。边缘计算则是…

涨薪技术|Kubernetes(k8s)之Pod生命周期(下)

上次推文我们学习了Pod生命周期&#xff08;上&#xff09;知识&#xff1a;相位、创建与终止、初始化容器&#xff0c;今天继续分享完余下的3个知识&#xff1a;钩子函数、容器探测、重启策略。 01钩子函数 钩子函数能够感知自身生命周期中的事件&#xff0c;并在相应的时刻…

谷歌手机LEA流程

谷歌手机LEA流程 连接管理首次连接手机回连 业务管理音乐业务通话业务 链路切换管理 本篇文章简单介绍了谷歌手机使用LE Audio连接TWS耳机中的实现细节&#xff0c;强调了持续广播机制、业务差异化处理、链路切换逻辑及加密安全性。核心目标是优化低功耗音频连接的稳定性和资源…