文档章节

swagger入门及swagger-maven-plugin使用

v1-alpha
 v1-alpha
发布于 2016/04/16 15:29
字数 763
阅读 6.8K
收藏 4

##swagger Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful风格的Web服务。推荐-翻译

swagger=specification+tools(前端用户界面、底层代码库、商业API管理解决方案)

swagger规范之于REST 类比 WSDL之于WebService

swagger入门1——what is swagger

##swagger规范

The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

It includes information on how to define paths, parameters, responses, models, security and more

swagger规范

##swagger工具 swagger UI:无依赖的HTML、JS和CSS的应用,根据swagger的json文件自动生成api文档和沙箱测试。

  1. 把swagger ui的dist目录以第三方js组件的方式添加到web应用;
  2. 修改index.html中window.swaggerUi =new SwaggerUi({});里的初始化参数url为swagger json文件路径,可以是普通js文件,也可以是后台动态生成json;
  3. 本地化:在index.html里添加lang/translator.js和lang/zh-cn.js;

swagger editor: swagger规范文件编辑器
swagger-core: Swagger implementation for Java/Scala. Has integration with JAX-RS (Jersey, Resteasy, CXF...), Servlets and Play Framework.

binder-swagger-java: binder-swagger-java was designed to help construct the swagger object, corresponding to swagger.json, and let it accessible from swagger ui or other http visitors.

springfox: Integrates with Spring MVC with support for Swagger 1.2 and Swagger 2.0 spec.

swagger-maven-plugin:Support Swagger Spec 2.0, integrate with JAX-RS & Spring MVC project, and easily generate swagger.json & a static document during build phase.

swagger工具

##swagger-maven-plugin使用

swagger-maven-plugin用来扫描类生成swagger.json规范。基于支持JAX-RS和SpringMVC。注意:

  1. 扫描@Api注解的类;
  2. 只有@ApiOperation,@RequestMapping注解并带有method属性的方法才会被识别;
  3. 带@ApiParam注解的参数才会被识别;
  4. SpringMVC扫描参数识别类型规则:逻辑在SpringSwaggerExtension
    | springMVC注解 | 参数类型 |
    |---------------|---------------------------|
    | RequestParam |QueryParameter query |
    | PathVariable |PathParameter path |
    | RequestHeader |HeaderParameter header |
    | CookieValue |CookieParameter cookie |
    | RequestPart |FormParameter formData|
    | ModelAttribute|QueryParameter query |
    | 其他 | BodyParameter body |
  5. maven插件的配置参数需要包括:info, info/title, info/version, locations(需要生成规范的类名/包名)
  6. 参数的schema属性是object类型并properties为空,swaggerui会报错:如参数是Object类型,

##swagger-maven-plugin修改扩展 swaggerUI生成的doc文档比javadoc文档更容易在团队中传阅交流。

工程在集成构建时把生成的swagger规范文件上传到指定目录swagger-dir,带swaggerUI的基础web应用会扫描swagger-dir目录,返回swagger.json的列表到页面。swagger-maven-plugin只针对REST API,对于普通API需要另做处理:新增继承AbstractDocumentSource的PSMavenDocumentSource,继承AbstractReader的PSApiReader。
修改点:

  1. 默认增加一个类全名的tag标签;
  2. springMVC默认method=post,如果@RequstMapping中没有写明method的方法也可以识别;
  3. 对于非REST的API,默认path为方法签名,默认method为post
  4. @ApiParam没写明name属性则自动识别,在此使用String[] org.springframework.core.ParameterNameDiscoverer.getParameterNames(Method method)
  5. 增加插件配置参数:swaggerFileName指定生成的swagger规范的文件名
    修改后swagger-maven-plugin代码
    修改后swagger-maven-plugindemo

© 著作权归作者所有

上一篇: 踩坑之变量命名
下一篇: bug记录
v1-alpha

v1-alpha

粉丝 6
博文 64
码字总数 78948
作品 0
厦门
程序员
私信 提问
加载中

评论(0)

Build RESTful APIs with Spring MVC: Swagger

Visualizes REST APIs with Swagger Swagger is widely used for visualizing APIs, and with Swagger UI it provides online sandbox for frontend developers. Visualizes REST APIs Sprin......

hantsy
2016/07/25
176
0
使用springfox 集成swagger 与spring mvc

创建一个maven 模块 将springfox相关的配置都配置在一个单独的api模块中,可以把这个模块当成web应用跑起来。 在需要引入swagger注解的模块中引入相应的依赖。 在api模块中添加初始化swagger...

java9
2016/07/29
1.6K
0
smart-doc 1.7.9 发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。 smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解...

上官胡闹
2019/12/16
1.6K
6
Springfox与SpringMvc集成实现接口文档化

准备环境 一个web服务器(我使用的是tomcat、当然nginx都可以) eclipse开发环境使用SpringMvc框架的源码(我使用springfox官网提供的demo) 下载swagger-ui源码 实现目的 eclipse中启动后台项目...

zzuqiang
2016/11/24
343
0
SpringBoot使用docker部署简单入门

当然这里需要先安装一下docker并且启动,这个大家可以参考网上海量的信息,比如菜鸟教程。 创建一个项目,然后在这里使用spring boot 2.0的版本。 然后加入如下的依赖,加入swagger依赖的包,...

woshixin
2019/07/03
77
0

没有更多内容

加载失败,请刷新页面

加载更多

为什么是super.super.method(); Java中不允许?

我读了这个问题,并认为如果可以写的话,很容易解决(不是没有它就不能解决): @Overridepublic String toString() { return super.super.toString();} 我不确定在很多情况下它是否有...

javail
15分钟前
64
0
使用 Python 远程登陆服务器的最佳实践

公众号:《Python编程时光》,作者:明哥 在使用 Python 写一些脚本的时候,在某些情况下,我们需要频繁登陆远程服务去执行一次命令,并返回一些结果。 在 shell 环境中,我们是这样子做的。...

王炳明
17分钟前
50
0
Java Web 学习笔记(6)

过滤器 Filter 功能: 1、用来拦截传入的请求和传出的相应。 2、修改或以某种方式处理正在客户端和服务端之间交换的数据流。 如何使用? 与使用Servlet类似,Filter是JavaWeb提供的一个借口,...

JaneRoad
19分钟前
57
0
京东架构师教你如何Java性能调优权威指南pdf

由于细节内容实在太多啦,所以只把部分知识点截图出来粗略的介绍,每个小节点里面都有更细化的内容! 内容简介 本书主要为Java SE和Java EE应用的性能调优提供建议。具体来说包括以下几方面:...

白楠楠
19分钟前
56
0
一起了解 .Net Foundation 项目 No.8

.Net 基金会中包含有很多优秀的项目,今天就和笔者一起了解一下其中的一些优秀作品吧。 中文介绍 中文介绍内容翻译自英文介绍,主要采用意译、如与原文存在出入,请以原文为准。 IdentityMo...

Newbe36524
24分钟前
103
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部