文档章节

swagger入门及swagger-maven-plugin使用

v1-alpha
 v1-alpha
发布于 2016/04/16 15:29
字数 763
阅读 1660
收藏 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
码字总数 73046
作品 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

没有更多内容

加载失败,请刷新页面

加载更多

下一页

windbg学习记录

我开始熟练使用windbg是从帮助手册开始的,也就是.hh命令。 就像学习windows开发从msdn开始一样,微软的产品虽然不开源,但是文档做的是相当的好。然而那些开源的东西呢?开源的竞争力其实就...

simpower
7分钟前
0
0
学习scala的网站汇总

https://www.codacy.com/blog/how-to-learn-scala/

Littlebox
9分钟前
0
0
配置本地的cloud9开发环境

前言 说到在线IDE开发环境,cloud9是不能绕过的,cloud9支持很多语言,默认支持的就有Node.js,Python,Ruby,PHP,Go,更逆天的是,他还支持数据库,包括MySQL,MongoDB,Redis,SQLite。但...

Kefy
13分钟前
0
0
springcloud应用程序上下文层次结构

如果您从SpringApplication或SpringApplicationBuilder构建应用程序上下文,则将Bootstrap上下文添加为该上下文的父级。这是一个Spring的功能,即子上下文从其父进程继承属性源和配置文件,因...

itcloud
18分钟前
0
0
新程序员最爱的免费资源

简评:国外美女程序员推荐了她自己用过的一些免费资源,对新手比较友好的那种。 原作者 Ali Spittel,是个美女程序员,以下这些资源都是她自己试过的。以下「我」代表 Ali Spittel。 学 HTML...

极光推送
21分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部