Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
来源:互联网 发布:淘宝食品没有证能吗 编辑:程序博客网 时间:2024/05/04 04:41
转自:http://blog.csdn.net/fansunion/article/details/51923720和http://blog.csdn.net/wangnan9279/article/details/44541665和
https://www.2cto.com/kf/201502/376959.html
这里只做备份
集成示例demo下载:http://download.csdn.net/download/wqc19920906/10042478
swagger-ui下载:http://download.csdn.net/download/wqc19920906/10042745
swagger2.0版本以上的使用教程尚未整理,详情见官网。
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、使用介绍
什么是 Swagger?
Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。
浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息,包括附加的支持其他语言的库。
如何集成Swagger-springmvc到我们的项目中?
依赖:
Maven
Gradle
使用:
要最快捷地启动swagger-springmvc项目并且使用默认设置,推荐的方式是使用SwaggerSpringMvc插件
Spring Java Configuration
Spring xml Configuration
SwaggerSpringMvcPlugin XML Configuration
为了使用这个插件,你需要创造一个spring java配置类。使用spring的 @Configuration ,这个配置类必须被定义到你的xml上下文
SwaggerSpringMvcPlugin Spring Java Configuration
使用@EnableSwagger注解
自动注入SpringSwaggerConfig
定义一个或多个SwaggerSpringMvcPlugin实例,通过springs @Bean注解
二、碰到的问题
关于@API注解
在Swagger Annotation中:
在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。
在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。
ApiParam用于描述该API操作接受的参数类型
再接着,为项目的Model对象添加Swagger Annotation,这样Swagger Scanner可以获取更多关于Model对象的信息。
通过上面的步骤,项目已经具备了提供Swagger格式的API信息的能力,接下来,我们把这些信息和Swagger UI集成,以非常美观,实用的方式把这些API信息展示出来。
和Swagger UI的集成
首先,从github(https://github.com/wordnik/swagger-ui)上下载Swagger-UI, 把该项目dist目录下的内容拷贝到项目的resources的目录assets下。
然后,修改index.html, 把Swagger UI对象中的URL替换为自己的API路径。
最后,为了能访问到该页面,还需要在Service的Initialize方法中,添加AssetsBundle
最后的效果图:
二:Swagger与Spring MVC集成步骤
1.Maven关键配置
2. 插件配置 CustomJavaPluginConfig
3.复制swagger的相关js等静态资源到webapp目录。 swagger-ui.js之类的。 我copy过一次,但是有问题,最后从网上下载了一个项目,可以直接用的那种。 然后自己再逐步改造。
4.启动项目 http://localhost:8080/
三、常见swagger注解一览与使用最常用的5个注解
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
其它若干
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
其它若干
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
三、评价
Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。
Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。
四、参考资料
官网:http://swagger.io/
GitHub:
swagger-springmvc:https://github.com/martypitt/swagger-springmvc
swagger-ui:https://github.com/swagger-api/swagger-ui
swagger-core:https://github.com/swagger-api/swagger-core
swagger-spec:https://github.com/swagger-api/swagger-spec
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档
- Spring3 MVC中使用Swagger生成API文档
- Swagger生成API文档
- Spring MVC 集成 Swagger,API文档自动生成~
- 在Spring中使用Springfox和swagger生成restful风格的API文档
- 使用Swagger,Swagger-UI生成REST API接口文档
- swagger ui和spring boot集成生成api文档
- 使用 swagger 自动生成 API 文档
- 如何使用 Grape-Swagger 生成 API 文档
- SpringMVC中使用swagger为api接口生成文档
- SpringBoot中使用Swagger生成RESTful规范API文档
- vivo出席GTI论坛分享最新研发成果
- Hyperloop One 与印度政府已进入谈判期,年底前决定是否在印度建设超级高铁
- 微信公众平台“账号迁移”开启公测,暂不支持个人账号
- Facebook 拟在乌干达铺设 500 英里光纤网络
- 几个搜索命令(find),文件名后缀,linux和Windows之间传文件
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- C语言基础练习8
- Oracle 游标使用全解
- 百度联手德甲 用人工智能推动体育IP生态建设
- vivo携手高通亮相MWC 双摄Hi-Fi旗舰引发行业围观
- 华为推“创新城市”:用基站为无人机进行无线充电
- 雷军谈手机行业正经历最困难的时候,小米“造芯片”要把握自己的命运
- anaconda 在linux(centos7) 下的安装(虚拟机离线情况下)
- POJ 3684 Physics Experiment【模拟】