简介:Swagger是一种Rest API的 简单但强大的表示方式,标准的,语言无关,这种 表示方式不但人可读,而且机器可读。 可以作为Rest API的交互式文档,也可以作为Rest API的形式化的接口描述,生成客户端和服务端的代码。
下面结合比较常见的场景,大概说下在Springboot下如何使用swagger来管理接口,以便前后端开发人员能够很好的做接口的对接,同时也利于接口的后续维护开发。
1. maven里引入swagger所需jar包:
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger2.version}</version> </dependency> </dependencies>
2.指定swagger的一些静态资源文件配置,一般用一个类来管理维护:
@Configuration @EnableSwagger2 public class SwaggerConfiguration extends WebMvcConfigurerAdapter { @Value("${swagger2.basePackage:com.xxx}") private String swagger2BasePackage; @Value("${swagger2.title:系统API文档}") private String swagger2Title; @Value("${swagger2.api.version:1.0}") private String apiVersion; @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars*").addResourceLocations("classpath:/META-INF/resources/webjars/"); } @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) .select().apis(RequestHandlerSelectors.basePackage(swagger2BasePackage)) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title(swagger2Title).version(apiVersion).build(); } }
3. 如何使用?
这一步我会用比较常见的业务场景去描述接口:
首先Controller层(类)上需要这样注解:
@Api(value = "SWAGGER接口") @RestController @RequestMapping(value = "/api/swagger/user") public class SwaggerController{ //.... }
1)请求参数对应一组String字符串或者一个VO,返回结果是单个对象
此时方法一定要有返回而不能是void
eg:根据输入条件查询某条记录
@ApiOperation(value="获取用户详细信息", notes="根据参数来获取用户详细信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Long", paramType = "query"), @ApiImplicitParam(name = "name", value = "用户名字", required = true, dataType = "String", paramType = "query"), @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Long", paramType = "query") }) @RequestMapping(value="", method=RequestMethod.GET) @PostMapping("/find1") public User find (@ModelAttribute User user) {//@ModelAttribute User user 等效于Long id, String name; Long age; return new User(); }
其中User类如下:
//@ApiModel(value="User", description="用户对象") public class User { @ApiModelProperty(value = "用户ID", required = true) private Long id; @ApiModelProperty(hidden = true) private String name; @ApiModelProperty(value = "用户年龄") private Long age; public void setId(Long id) { this.id = id; } public void setName(String name) { this.name = name; } public void setAge(Long age) { this.age = age; } public Long getId() { return id; } public String getName() { return name; } public Long getAge() { return age; } }
User类是对应查询条件或查询结果组成的实体~,每个属性需要用@ApiModelProperty去描述每个字段的含义;User类上的@ApiModel注解可以选择性给出。
访问swagger接口描述页面只需启动项目(这里是springboot),然后输入http://localhost:8080/swagger-ui.html#!即可访问,我们点击对应的Controller和接口,可以看到:
Paramters就是描述输入参数的区域,而Response则是输出的描述,Response可以切换到Model,可以看到输出的字段的具体含义:
2)请求参数是复合的,这时候必须对应一个实体类,如:
//@ApiModel(value="Params", description="传入参数") public class Params { @ApiModelProperty(name="param1", value = "参数1", required = true) private String param1; @ApiModelProperty(name="input", value = "输入", required = true) private List<Input> input; public String getParam1() { return param1; } public void setParam1(String param1) { this.param1 = param1; } public List<Input> getInput() { return input; } public void setInput(List<Input> input) { this.input = input; } }
返回是一个集合类型:
@ApiOperation(value="获取用户信息集合", notes="根据输入类型来获取用户信息集合") @PostMapping("/find2") @ApiResponse(response = User.class, responseContainer="List", code = 200, message = "请求成功") public List<User> find2(@ApiParam(value="传入参数类型", required=true) @RequestBody Params params) { return new ArrayList<User>(); }
ui上点击对应方法,可以看到:
可以看到,现在无论是对于接口里再复杂的输入和输出,都能比较清楚地看到每个属性(字段)的含义,以及可以在swagger的ui上直接用Try it out 按钮来测试接口的可用性。
swagger可以很好地帮助我们管理项目接口~,以及不同业务侧之间的接口对接工作。
相关推荐
swagger是一个管理数据接口的框架,通过注解的方式、网页的形式自动帮我们生成接口相关的信息,相比以前文档的方式撰写的接口,swagger更加便捷、高效,省力。
Swagger 让部署管理和使用功能强大的API从未如此简单。 一、使用介绍 什么是 Swagger? Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络...
springboot集成swagger源码,实现后台接口管理,提供后台开发人员接口测试,前端开发人员接调用,接口显示,接口查询和测试
基于swagger文档,进行左侧菜单改造,添加左侧菜单,快速导航菜单接口,后台接口api目录用-分割,如: XX系统-XX管理-XX列表
关于swagger介绍的ppt,Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到...
生成json文件,供swagger接口文档测试使用,可打开或关闭.swagger支持接口多版本分组管理.支持restful path路由参数校验.支持自定义响应体结构.支持自定义多层级swagger model.支持自定义前置动作.支持自定义拦截动作....
asp.net core api+jwt+swagger CRM管理系统 后台接口
spring boot + swagger2集成api接口文档,springBoot+swagger+mysql 搭建的一个项目。可以启动。可供参考使用; Swagger是一个规范和完整的框架,用于生成、...Swagger 让部署管理和使用功能强大的API从未如此简单。
使用Swagger管理接口文档 使用Postman调试接口 使用RAP Mock数据 使用JMeter做接口自动化测试 二,存在的问题 以及不同的工作量的问题,造成的问题是多个系统之间的数据交替,导致协作低效,替代出问题,开发人员...
主要给大家介绍了关于.NET Core利用swagger进行API接口文档管理的相关资料,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧。
主要给大家介绍了关于Asp.Net Core WebAPI使用Swagger时API隐藏和分组的相关资料,文中通过示例代码介绍的非常详细,对大家学习或者使用Asp.Net Core具有一定的参考学习价值,需要的朋友们下面来一起学习学习吧
1、部分业务相关CRUD接口和模板管理相关接口。 2、统一异常处理。 3、分页功能:aop实现默认分页赋值。 4、统一结果返回。 5、策略工厂模式:用于不同业务逻辑的实现。 6、uid生成工具。 7、集成swagger在线接口文档...
使用Maven搭建的ssm,方便管理jar包,整合了swagger2,便于管理接口文档。 下载资源了没有运行成功的请私信我。
作为后端程序开发,我们多多少少写过几个后台接口项目,不管是编写手机端接口,还是目前比较火热的前后端分离项目,前端与后端都是由不同的工程师进行开发,...Swagger 让部署管理和使用功能强大的API从未如此简单。
2、项目使用swagger管理接口文档,前端开发人员只需查看接口文档即可了解各接口细节 3、后台项目包括数据库在内,均编写了较为详细的注释 三、数据库相关说明 1、本项目数据库使用MySQL8.0版本开发,产业化中心...
使用SpringBoot+SpringJPA+Swagger+Shiro快速搭建前后端分离的权限管理系统源码,方便二次开发,项目经过严格测试,确保可以运行! 快速搭建前后端分离的权限管理系统 提供一套基于SpringBoo+shiro的权限管理思路. ...
字典管理:维护系统中经常使用的字典数据,如:性别,状态 参数管理:系统动态配置常用参数,如:分页数,前端主题色等 通知管理:系统通知&公告信息的发布维护 日志管理:操作日志和登录日志 接口文档:根据业务...
一个 SpringBoot+ Layui 的社区物业管理系统,前端使用 Layui,Ajax,后端使用 MyBatisPlus 方便 sql 编写,使用 swagger2 编写接口文档,使用 mysql 作为数据库。 功能 管理员: 核心业务管理、车位收费、物业收费...
SpringMVC精品资源--SERVER-API 是一个gui的web接口管理工具,基于 swagger-ui 的