1. Swagger是什么?

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

官方说法:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

个人觉得,swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中,发生过多次:修改代码但是没有更新文档,前端还是按照老旧的文档进行开发,在联调过程中才发现问题的情况(当然依据开闭原则,对接口的修改是不允许的,但是在项目不稳定阶段,这种情况很难避免)。

2. spring boot 集成 Swagger

目前维护的系统是基于springboot框架开发的,因此本文会详细描述springboot与swagger集成的过程。

spring-boot系统集成swagger需要进行如下操作:

  1. 添加maven依赖,需要在系统的pom中添加如下依赖:

     <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
    </dependency>
  2. 添加swagger配置文件,配置文件如下:

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig { @Bean
    public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
    .select() // 选择那些路径和api会生成document
    .apis(RequestHandlerSelectors.any()) // 对所有api进行监控
    .paths(PathSelectors.any()) // 对所有路径进行监控
    .build();
    } }

    通过注解EnableSwagger2声明Swagger的可用性,此处会定义一个类型为Docket的bean,
    关于docket类的说明如下:

    A builder which is intended to be the primary interface into the
    swagger-springmvc framework.Provides sensible defaults and convenience
    methods for configuration.

    Docket的select()方法会提供给swagger-springmvc framework的一个默认构造器(ApiSelectorBuilder),这个构造器为配置swagger提供了一系列的默认属性和便利方法。

  3. 测试

    通过访问:http://localhost:8080/your-app-root/v2/api-docs ,能测试生成的api是否可用。此时返回的是一个json形式的页面,可读性不好。可以通过Swagger UI来生成一个可读性良好的api页面。具体做法就是,在pom中添加相关依赖。如下:

    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
    </dependency>

    再次访问:http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可读性较好的api文档页面。

  4. 注意:

    1. http://localhost:8080/your-app-root/v2/api-docsyour-app-root指的你的wabapp的根路径,我目前的webapp就默认在根路径下,所以地址是:http://localhost:8080/v2/api-docs
    2. spring-mvc上引用swagger需要做其他相关的配置,具体请查看参考文献
    3. swagger对restful风格的api支持的比较好,非restful风格的api支持的不是很好,对于非restful风格的api或者其他语言(非java语言)可以采用 http://editor.swagger 编辑器来收工完成相关的API编写

参考文献

  1. swagger-2-documentation-for-spring-rest-api

Swagger使用总结(十九)的更多相关文章

  1. 无废话ExtJs 入门教程十九[API的使用]

    无废话ExtJs 入门教程十九[API的使用] extjs技术交流,欢迎加群(201926085) 首先解释什么是 API 来自百度百科的官方解释:API(Application Programmin ...

  2. Python之路【第十九章】:Django进阶

    Django路由规则 1.基于正则的URL 在templates目录下创建index.html.detail.html文件 <!DOCTYPE html> <html lang=&q ...

  3. Bootstrap <基础二十九>面板(Panels)

    Bootstrap 面板(Panels).面板组件用于把 DOM 组件插入到一个盒子中.创建一个基本的面板,只需要向 <div> 元素添加 class .panel 和 class .pa ...

  4. Bootstrap <基础十九>分页

    Bootstrap 支持的分页特性.分页(Pagination),是一种无序列表,Bootstrap 像处理其他界面元素一样处理分页. 分页(Pagination) 下表列出了 Bootstrap 提 ...

  5. Web 开发人员和设计师必读文章推荐【系列二十九】

    <Web 前端开发精华文章推荐>2014年第8期(总第29期)和大家见面了.梦想天空博客关注 前端开发 技术,分享各类能够提升网站用户体验的优秀 jQuery 插件,展示前沿的 HTML5 ...

  6. Web 前端开发精华文章集锦(jQuery、HTML5、CSS3)【系列十九】

    <Web 前端开发精华文章推荐>2013年第七期(总第十九期)和大家见面了.梦想天空博客关注 前端开发 技术,分享各种增强网站用户体验的 jQuery 插件,展示前沿的 HTML5 和 C ...

  7. Python之路【第十九篇】:爬虫

    Python之路[第十九篇]:爬虫   网络爬虫(又被称为网页蜘蛛,网络机器人,在FOAF社区中间,更经常的称为网页追逐者),是一种按照一定的规则,自动地抓取万维网信息的程序或者脚本.另外一些不常使用 ...

  8. KALI LINUX WEB 渗透测试视频教程—第十九课-METASPLOIT基础

    原文链接:Kali Linux Web渗透测试视频教程—第十九课-metasploit基础 文/玄魂 目录 Kali Linux Web 渗透测试视频教程—第十九课-metasploit基础..... ...

  9. NeHe OpenGL教程 第三十九课:物理模拟

    转自[翻译]NeHe OpenGL 教程 前言 声明,此 NeHe OpenGL教程系列文章由51博客yarin翻译(2010-08-19),本博客为转载并稍加整理与修改.对NeHe的OpenGL管线 ...

  10. NeHe OpenGL教程 第二十九课:Blt函数

    转自[翻译]NeHe OpenGL 教程 前言 声明,此 NeHe OpenGL教程系列文章由51博客yarin翻译(2010-08-19),本博客为转载并稍加整理与修改.对NeHe的OpenGL管线 ...

随机推荐

  1. 什么是虚拟DOM?

    (摘抄自一篇文章,觉得这里写得非常不错,所以单独放出来,希望能对大家有帮助.)React为啥这么大?因为它实现了一个虚拟DOM(Virtual DOM).虚拟DOM是干什么的?这就要从浏览器本身讲起 ...

  2. sql server 驱动程序在 \Device\RaidPort0 上检测到控制器错误。

    sql server 驱动程序在 \Device\RaidPort0 上检测到控制器错误. 错误情况,如下图: 原因分析:硬盘故障 解决办法:进行迁移

  3. Java-小技巧-003-static、final、static final的区别

    final可以修饰:属性,方法,类,局部变量(方法中的变量) final修饰的属性的初始化可以在编译期,也可以在运行期,初始化后不能被改变,jvm会将其分配到常量池中,程序不可改变其值: final修 ...

  4. Android开发新手问题

    因为最近在用空闲时间学习Android开发,期间确实遇到了一些问题.而且因为我之前在公司里一直都是在使用Eclipse进行开发,所以最初我学习Android时也就选择了Google的包含android ...

  5. SCons构建工具使用

    scons是一个Python写的自动化构建工具,和GNU make相比优点明显:    1. 移植性:python能运行的地方,就能运行scons    2. 扩展性:理论上scons只是提供了pyt ...

  6. zlib编译安装

    从http://www.zlib.net/下载了最新的源代码 zlib提供了vs sln文件,在zlib-1.2.8\contrib\vstudio\目录有 其中的zlibstat是编译为静态库zli ...

  7. VS Code 终端窗口无法输入命令的解决方案

    问题 今天打开vs code,打开终端窗口,发现不能输入命令了 解决方法 邮件桌面 vscode的快捷键,打开“兼容性”标签,勾选"以管理员身份运行此程序" 结果 修改之后重启vs ...

  8. 创建工具条ToolBar

    /***ToolBar***/ QToolBar * tlb_ImageOpen; QToolBar * tlb_VideoOpen; QToolBar * tlb_AudioOpen; void M ...

  9. 怎样使用CSS设置文字与文字间距距离?

    [文字与文字间距距离,字与字距离间距CSS如何设置?]如果你也遇到W3Cschool用户唐婷大小姐类似的问题不妨也到W3Cschool编程问答进行提问. 对于使用CSS解决字间距的方法W3Cschoo ...

  10. rails性能优化

    1,使用Unicorn或者Thin服务器替代默认的webrick.2,静态资源压缩合并,放到云存储上.3,同时可以使用rails的Turbolinks,使用js替换title和body,但也带来了js ...