文档章节

swagger入门及swagger-maven-plugin使用

v1-alpha
 v1-alpha
发布于 2016/04/16 15:29
字数 763
阅读 1498
收藏 4
点赞 1
评论 0

##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
博文 58
码字总数 72889
作品 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 ⋅ 0

使用springfox 集成swagger 与spring mvc

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

java9 ⋅ 2016/07/29 ⋅ 0

Springfox与SpringMvc集成实现接口文档化

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

zzuqiang ⋅ 2016/11/24 ⋅ 0

自动生成 API ChangeLog 组件 - swagger-diff

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

Sayi ⋅ 2017/12/19 ⋅ 0

Spring Boot+Swagger整合示例

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

centychen ⋅ 2016/11/01 ⋅ 5

Swagger-UI配置使用

Swagger-ui是一个用于提供restful接口api测试的工具,结合Springcloud引入后,可以部分代替像postman等 测试rest接口的工具。而且具有实时性,与其他系统对接时具有极大的方便性。 1、引入依...

0了凡0 ⋅ 2016/09/12 ⋅ 0

在 spring-boot 中使用 swagger--SwaggerSpringBootStarter

在spring-boot中使用swagger,可以实现对代码无侵入地集成swagger 使用时的项目配置 需要在spring boot项目中使用,下面按照使用maven构建项目,以及使用文件来配置进行介绍, 如果使用其他的...

阿信sxq ⋅ 2017/07/21 ⋅ 0

阿信sxq/SpringBootSwaggerStarter

SpringBootSwaggerStarter 在spring-boot中使用swagger,可以实现对代码无侵入地集成swagger 使用时的项目配置 需要在spring boot项目中使用,下面按照使用maven构建项目,以及使用文件来配置...

阿信sxq ⋅ 2017/07/21 ⋅ 0

API管理工具Swagger介绍及Springfox原理分析

swagger是一个API框架,号称世界上最流行的API工具。它提供了API管理的全套解决方案,比如API在线编辑器,API UI展示界面,代码生成器等诸多功能。 如果想引入swagger进行API管理。目前 spri...

中间件小哥 ⋅ 06/05 ⋅ 0

Dubbo 的 Swagger 服务文档 - swagger-dubbo

swagger-dubbo支持dubbo以swagger方式展示文档和rest风格的HTTP模拟测试,主要应用场景有以下几点: 通过dubbo与swagger的集成,提供接口文档的阅读 开发人员可以用它来自测服务接口,也可以...

Sayi ⋅ 06/07 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

行政区划代码转为字典形式

原数据为: http://www.mca.gov.cn/article/sj/xzqh/2018/201804-12/201804-06041553.html 手动替换了一下格式,并使用下面的代码处理. # 输入格式s = """110000:北京市110101:东城区1101...

漫步海边小路 ⋅ 18分钟前 ⋅ 0

android apk 签名

创建key,需要用到keytool.exe (位于C:\Program Files\Java\jdk1.6.0_10\bin目录下),使用产生的key对apk签名用到的是jarsigner.exe (位于C:\Program Files\Java\jdk1.6.0_10\bin目录下),把...

国仔饼 ⋅ 27分钟前 ⋅ 0

springcloud+jps+mybatis多数据库配置

多数据库配置 配置我们目录结构设置: config ---datasource ----jpa ----mybatis ----redis Datasource中是数据的相关配置 Jap中是springDatajpa的相关配置 Mybatis中是mybatis的相关配置 ...

大-智-若-愚 ⋅ 34分钟前 ⋅ 0

Spring mvc HandlerMapping 实现机制

概述 当DispatcherServlet接受到客户端的请求后,SpringMVC 通过 HandlerMapping 找到请求的Controller。 HandlerMapping 在这里起到路由的作用,负责找到请求的Controller。 Spring MVC 默认...

轨迹_ ⋅ 37分钟前 ⋅ 0

JavaScript零基础入门——(十)JavaScript的DOM基础

JavaScript零基础入门——(十)JavaScript的DOM基础 欢迎大家回到我们的JavaScript零基础入门,上一节课,我们了解了JavaScript中的函数,这一节课,我们来了解一下JavaScript的DOM。 第一节...

JandenMa ⋅ 今天 ⋅ 0

Weex起步

本教程假设你已经在你的本地环境安装了node 其实weex起步教程在 https://github.com/lilugirl/incubator-weex 项目说明文件中都已经有了,但为了有些同学看到英文秒变文盲,所以这里我重新写...

lilugirl ⋅ 今天 ⋅ 0

Jenkins实践1 之安装

1 下载 http://mirrors.jenkins.io/war/latest/jenkins.war 2 启动 java -jar jenkins.war 前提:安装jdk并配置环境变量 启动结果节选: ************************************************......

晨猫 ⋅ 今天 ⋅ 0

组合数学 1-2000 中,能被6或10整除的数的个数

1--2000 中,能被6或10整除的数的个数 利用集合的性质 能被6整除的个数 2000/6 = 333 能被10整除的个数 2000/10 = 200 能被6和10整除的个数 2000/30 = 66 能被6或10整除的个数 333+200-66 =...

阿豪boy ⋅ 今天 ⋅ 0

一篇文章学懂Shell脚本

Shell脚本,就是利用Shell的命令解释的功能,对一个纯文本的文件进行解析,然后执行这些功能,也可以说Shell脚本就是一系列命令的集合。 Shell可以直接使用在win/Unix/Linux上面,并且可以调用...

Jake_xun ⋅ 今天 ⋅ 0

大数据工程师需要精通算法吗,要达到一个什么程度呢?

机器学习是人工智能的一个重要分支,而机器学习下最重要的就是算法,本文讲述归纳了入门级的几个机器学习算法,加大数据学习群:716581014一起加入AI技术大本营。 1、监督学习算法 这个算法由...

董黎明 ⋅ 今天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部