目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有效解决前后端人员沟通难的问题。

下面我们使用SpringBoot结合swagger2生成Restful API文档。

一 搭建项目,引入依赖

新建一个spring-boot-swaager的项目,引入swaager2的依赖,由于swagger2的ui不是很美观,这里将使用开源的swagger-bootstrap-ui做为ui。

引入依赖

<!-- swaager2依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swaager2ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>

项目中配置swagger相关信息

@Configuration
@EnableSwagger2
public class configuration { @Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo(){
return new ApiInfoBuilder()
// 标题
.title("某某项目接口文档")
// 描述
.description("swagger2接口文档使用演示")
// 版本
.version("1.0")
// 许可证
.license("MIT")
// 许可证地址
.licenseUrl("www.xx.com")
// 服务端地址
.termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
// 联系信息
.contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","binzh303@163.com"))
.build();
}
}

访问路径,查看生成效果

文章中使用的这个ui,接口文档地址为ip:port/doc.html,生成的文档信息如下:

二 编写Restful接口

新建实体类

@ApiModel("用户实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
}

新建Restful接口

@Api(tags = "用户接口")
@RestController
@RequestMapping("person")
public class PersonController { @ApiOperation(value = "获取用户列表",notes = "根据name获取用户列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true),
@ApiImplicitParam(name = "age",value = "年龄",dataType = "int",required = true)
})
@GetMapping("/{name}")
public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
return new Person(name,age);
} @ApiOperation(value = "新增用户",notes = "根据用户实体类新增用户")
@ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
@PostMapping("add")
public int addPerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
} @ApiOperation(value = "更新用户信息",notes = "根据用户实体更新用户信息")
@ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
@PutMapping("update")
public int updatePerson(@RequestBody Person person){
if(StringUtils.isEmpty(person)){
return -1;
}
return 1;
} @ApiOperation(value = "删除用户信息",notes = "根据用户名删除用户信息")
@ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true)
@DeleteMapping("/{name}")
public int deletePerson(@PathVariable(name = "name") String name){
if(StringUtils.isEmpty(name)){
return -1;
}
return 1;
}
}

三 swagger文档简介

我就直接用图来表示了,这样看着也更加直观

swagger2注解对应到文档上的表现形式如上。swagger2支持在线调试,打开某个具体的接口,根据提示填写对应的参数,点击发送就可返回响应结果。

此是spring-boot-route系列的第五篇文章,这个系列的文章都比较简单,主要目的就是为了帮助初次接触Spring Boot 的同学有一个系统的认识。本文已收录至我的github,欢迎各位小伙伴star

githubhttps://github.com/binzh303/spring-boot-route

点关注、不迷路

如果觉得文章不错,欢迎关注点赞收藏,你们的支持是我创作的动力,感谢大家。

如果文章写的有问题,请不要吝啬,欢迎留言指出,我会及时核查修改。

如果你还想更加深入的了解我,可以微信搜索「Java旅途」进行关注。回复「1024」即可获得学习视频及精美电子书。每天7:30准时推送技术文章,让你的上班路不在孤独,而且每月还有送书活动,助你提升硬实力!

spring-boot-route(五)整合Swagger生成接口文档的更多相关文章

  1. spring-boot-route(六)整合JApiDocs生成接口文档

    上一篇文章中介绍了使用Swagger生成接口文档,非常方便,功能也十分强大.如果非要说Swaager有什么缺点,想必就是注解写起来比较麻烦.如果我说有一款不用写注解,就可以生成文档的工具,你心动了吗? ...

  2. asp.net core 使用 swagger 生成接口文档

    参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...

  3. webapi 利用webapiHelp和swagger生成接口文档

    webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...

  4. .net core 使用 swagger 生成接口文档

    微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...

  5. asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档

    asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...

  6. SpringBoot整合Swagger3生成接口文档

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与swagger2相比新版的swagg ...

  7. Django使用swagger生成接口文档

    参考博客:Django接入Swagger,生成Swagger接口文档-操作解析 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文 ...

  8. Go语言使用swagger生成接口文档

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服 ...

  9. Spring Boot 集成 Swagger生成接口文档

    目的: Swagger是什么 Swagger的优点 Swagger的使用 Swagger是什么 官网(https://swagger.io/) Swagger 是一个规范和完整的框架,用于生成.描述. ...

随机推荐

  1. 接口测试中postman环境和用例集

    postman的环境使用 postman里有环境的设置,就是我们常说的用变量代替一个固定的值,这样做的好处是可以切换不同的域名.不同的环境变量,不同的线上线下账户等等场景.下面就看下怎么用吧. 创建一 ...

  2. Istio可观测性

    Istio可观测性 Istio的可观测性包括metrics,日志,分布式链路跟踪以及可视化展示.下面主要介绍如何在istio中部署基于Prometheus的metrics监控,基于jaeger的链路跟 ...

  3. 还在写if/else if ... ?

    在日常开发中,我们经常会写出很多 if  else if ... 很多看起来又长又糟糕的代码, 那么策略模式你该去get 了. 点我查看哦!

  4. Unity中的枚举和标志

    译林军 宿学龙|2014-04-10 08:56|9007次浏览|Unity(377)0 枚举和标志 今天的主题是枚举,它是C#语言中的一个很有帮助的工具,可以增强代码的清晰度以及准确性. 枚举一系列 ...

  5. 关于js与jquery中的文档加载

    jquery中的$(document).ready()类似于javascript中的window.onload(),但是其中还是有很大区别的 1.jquery中的可以简化为$().ready(),$( ...

  6. SSM整合+WebUpload使用(spring+springmvc+mybatis+maven)

      SSM框架整合以及webupload的集成与使用 在项目中最近用到了webupload.js,也方方面面遇到了不少问题,比如上传文件前对表单参数校验,当校验失败不予提交,及在文件上传成功后,选择同 ...

  7. npm 报错 cb.apply is not a function

    解决方法1 目录C:\Users(your username)\AppData\Roaming 有个npm文件夹 删除如果没有 npm cache文件cmd下运行 npm clean cache —f ...

  8. 第一课、python基础学习笔记

    自动化非自动化的区别 自动化测试就是让机器按照人的想法把功能全部跑一遍 自动化测试的过程,让我们写一段程序去测试另一段程序是否正常的过程 Java 编译型语言,   编码-->编译-->解 ...

  9. 关于while (~scanf("%d %d", &m, &n))的用法

    其功能是循环从输入流读入m和n,直到遇到EOF,有如下关系: while (~scanf("%d %d", &m, &n)) ↔ while (scanf(&quo ...

  10. Azure Storage 系列(五)通过Azure.Cosmos.Table 类库在.Net 上使用 Table Storage

    一,引言 上一篇文章我们在.NET 项目中添加了 “WindowsAzure.Storage” 的 NuGet 包进行操作Table 数据,但是使用的 “WindowsAzure.Storage”  ...