文档章节

swagger入门及swagger-maven-plugin使用

v1-alpha
 v1-alpha
发布于 2016/04/16 15:29
字数 763
阅读 1821
收藏 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

© 著作权归作者所有

共有 人打赏支持
v1-alpha

v1-alpha

粉丝 5
博文 62
码字总数 73104
作品 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
121
0
使用springfox 集成swagger 与spring mvc

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

java9
2016/07/29
997
0
Springfox与SpringMvc集成实现接口文档化

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

zzuqiang
2016/11/24
182
0
自动生成 API ChangeLog 组件 - swagger-diff

swagger-diff 自动生成 API ChangeLog 组件 用来比较两个由Swagger生成的API文档,对参数、返回类型、路径进行深度比较,并输出差异(HTML格式、Markdown格式),适用于自动生成接口变更文档。...

Sayi
2017/12/19
76
0
Spring Boot+Swagger整合示例

微服务的概念最近几年越来越火,目前有不少框架适合用于搭建微服务,Spring Boot应该是不少公司的选择(因为不少公司原来就是用Spring的,改造成本较低)。 微服务对外开放接口一般都是通过R...

centychen
2016/11/01
1K
5

没有更多内容

加载失败,请刷新页面

加载更多

linux使用ntfs-3g操作ntfs格式硬盘

Linux内核目前只支持对微软NTFS文件系统的读取。 NTFS-3G 是微软 NTFS 文件系统的一个开源实现,同时支持读和写。NTFS-3G 开发者使用 FUSE 文件系统来辅助开发,同时对可移植性有益。 安装 ...

linuxprobe16
今天
1
0
kubeadm部署kubernetes集群

一、环境要求 这里使用RHEL7.5 master、etcd:192.168.10.101,主机名:master node1:192.168.10.103,主机名:node1 node2:192.168.10.104,主机名:node2 所有机子能基于主机名通信,编辑...

人在艹木中
今天
10
0
Shell特殊符号总结以及cut,sort,wc,uniq,tee,tr,split命令

特殊符号总结一 * 任意个任意字符 ? 任意一个字符 # 注释字符 \ 脱义字符 | 管道符 # #号后的备注被忽略[root@centos01 ~]# ls a.txt # 备注 a.txt[root@centos01 ~]# a=1[root@centos01...

野雪球
今天
3
0
OSChina 周二乱弹 —— 程序员圣衣

Osc乱弹歌单(2018)请戳(这里) 【今日歌曲】 @达尔文:分享Skeeter Davis的单曲《The End of the World》 《The End of the World》- Skeeter Davis 手机党少年们想听歌,请使劲儿戳(这里...

小小编辑
今天
20
0
[ python import module ] 导入模块

import moudle_name ----> import module_name.py ---> import module_name.py文件路径 -----> sys.path (这里进行查找文件) # from app.web import Personimport app.web.Person as Pe......

_______-
昨天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部