一、What is swagger?

官方介绍Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful Web Service。
专业角度:Swagger是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二、Why use the swagger?

  1. 讲个故事:在2014年时候,我和另一个小伙伴加入到一个实验室,开始了我们漫长的应用开发之路(这也是第一次做项目)。因为只有两个人,我做后台,他做Android,分工很明确的。在一开始,我们并没有关注API相关的内容,随手拈来,我说什么,他就调用什么。当然,也没有什么API文档提供。以至于到现在,我想更新升级系统,才发现,我们写的代码是有多烂,连自己都不忍心去看的。所以说在项目开始就定一个契约,双方(前端后台)就API相关的内容,包括路径、参数、类型等达成一致,当然,这份契约并不是一旦创建就不能修改的,而且,如果一开始没有设计好,很有可能会频繁的修改。
  2. 作为一个很懒的码代码的猿呢,对于一些API的理解总是很模糊不清,但是,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。所以说,API文档应该有直接运行的能力。而Swagger就是这样的一个东西,它可以为已有项目的生成具备执行能力的样式化API文档,这样可以极大的方便程序员对前端后台进行对接整合。

三、use the swagger

1. 开发环境介绍
  • maven 3.3
  • jdk 8+
  • spring 4.2.5
  • mybatis 3.4.1
  • swagger 1.0.2
2. 在pom.xml文件中添加swagger相关依赖
<!-- swagger-mvc -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.6</version>
</dependency>
<!-- swagger-mvc -->
3. 自定义对swagger的配置

对于swagger的配置,其实对自定义一个与swagger相关的Config类,可以通过Java编码的实现配置。代码如下:

package com.hp.common.swagger;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; /**
*
* @ClassName: SwaggerConfig.java
* @Description: Swagger配置类
*
* @version: v1.1.0
* @author: xiangdong
* @date: Mar 16, 2017
*/
public class SwaggerConfig extends WebMvcConfigurerAdapter { private SpringSwaggerConfig springSwaggerConfig; @Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
} /**
* 链式编程 来定制API样式 后续会加上分组信息
*
* @return
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
} private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo("API接口测试平台",
"提供后台所有Restful接口", "www.flyeast.top",
"shexd1001@gmail.com", "β客栈", "www.flyeast.top");
return apiInfo;
} @Override
public void configureDefaultServletHandling(
DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
}
3. 注入SwaggerConfig类

上面这段对swagger进行了基本的配置,现在需要将其注入到spring容器中,完成在程序加载之后对所有接口扫描解析的功能呢,在spring相关的配置文件中加入以下代码:

    <!-- swagger配置信息 -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
4. 配置需要解析的接口方法

以下代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。关于其他注解,可以查看源码或其他帮助文档;

/**
* DELETE 删除用户
* @return
*/
@ApiOperation(value = "删除用户信息", notes = "删除用户", httpMethod = "DELETE", produces = MediaType.APPLICATION_JSON_VALUE)
@RequiresPermissions("sysuser:list:delete")
@RequestMapping(value = "/list/{accountId}/delete", method = RequestMethod.DELETE)
@ResponseBody
public AjaxResult delete(@PathVariable Long accountId) {
systemUserService.deleteSysUser(accountId);
return success(true);
}
5. 对Swagger-UI进行配置

Swagger扫描解析得到的是一个json文档,所以对于用户使用不是很方便,但是通过swagger-ui,可以友好的展示解析得到的接口说明内容。
这里 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/目录下。
修改index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,我们需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,如http://localhost:8080/CloudTi/api-docs

6. 运行项目,访问URL

URL是自己在index.html中定义的URL


作者:Xiangdong_She
链接:http://www.jianshu.com/p/f76d2c421422
來源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。

swagger的说明、配置及使用的更多相关文章

  1. Spring boot集成Swagger,并配置多个扫描路径

    Spring boot集成Swagger,并配置多个扫描路径 1:认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目 ...

  2. Swagger插件netcore配置

    步骤一. Nuget Packages安装,使用程序包管理器控制台,安装命令:Install-Package Swashbuckle.AspNetCore -Pre 步骤二. 在Startup 文件中 ...

  3. Swagger本地环境配置

    一.技术背景 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远.而前后端的唯一联系便是 API 接口,与此同 ...

  4. 使用Autofac 依赖注入及 swagger 之startup配置

    言语有限,代码如下: public IServiceProvider ConfigureServices(IServiceCollection services) { services .AddCor ...

  5. .NetCore WebApi——Swagger简单配置

    在前后端分离的大环境下,API接口文档成为了前后端交流的一个重点.Swagger让开发人员摆脱了写接口文档的痛苦. 官方网址:https://swagger.io/ 在.Net Core WebApi ...

  6. Swagger学习(四、配置API文档的分组)

    完整示例 代码结构 运行效果 SwaggerConfig.class @Configuration //变成配置文件 @EnableSwagger2 //开启swagger2 public class ...

  7. Swagger配置与使用

    问题:前后端分离时代的到来 前端需要测试后端数据 后端提供接口,实时更新接口的改动 一.Swagger简介 号称世界上最流行的api框架 Restful api文档在线自动生成工具-->api文 ...

  8. 《Asp.Net Core3 + Vue3入坑教程》-Net Core项目搭建与Swagger配置步骤

    简介 <Asp.Net Core3 + Vue3入坑教程> 此教程仅适合新手入门或者前后端分离尝试者.可以根据图文一步一步进操作编码也可以选择直接查看源码.每一篇文章都有对应的源码 教程后 ...

  9. 微服务之十四如何在 Ocelot 网关中配置多实例 Swagger 访问

    一.介绍 当我们开发基于微服务的应用程序的时候,有一个环节总是跳不过去的,那就是要创建 WebApi,然后,我们的应用程序基于 WebApi 接口去访问.在没有 Swagger 以前,我们开发好了 W ...

  10. swagger的作用和配置使用

    纯API项目中 引入swagger可以生成可视化的API接口页面     引入包 nuget包: Swashbuckle.AspNetCore(最新稳定版) 配置 1.配置Startup类Config ...

随机推荐

  1. Iconfont在移动端应用的问题

    关于部分奇葩用户代理不显示字体图标 以酷派为代表的部分安卓手机自带浏览器.微信/QQ WebView 等用户代理无法正常显示 Icon Font,原因可能是这些用户代理无法正确处理伪元素 conten ...

  2. js jQuery 右键菜单 清屏

    主要用到了oncontextmenu事件,在oncontextmenu事件中使用return false 屏蔽掉原生右键菜单,再使用event获取鼠标的坐标位置,设置自定义菜单的位置. http:// ...

  3. 【转】Memcached之缓存雪崩,缓存穿透,缓存预热,缓存算法

    缓存雪崩 缓存雪崩可能是因为数据未加载到缓存中,或者缓存同一时间大面积的失效,从而导致所有请求都去查数据库,导致数据库CPU和内存负载过高,甚至宕机. 解决思路: 1,采用加锁计数,或者使用合理的队列 ...

  4. tomcat部署时war和war exploded区别

    war模式—-将WEB工程以包的形式上传到服务器 war exploded模式—-将WEB工程以当前文件夹的位置关系上传到服务器

  5. 解决连锁零售行业IT运维管理四大困境

    解决连锁零售行业IT运维管理四大困境   中国近年来,连锁零售行业进入了行业的发展高潮,迅速崛起一批大型连锁业态.而随着IT技术的不断进步,连锁零售企业已经步入IT信息化快速发展的重要阶段:在面对激烈 ...

  6. e805. 监听JProgressBar的数值变化

    Whenever the value of a progress bar is changed, a change event is fired. In fact, the event is also ...

  7. Autofac应用总结

    准备: public interface IDAL { void Insert(string commandText); } public class SqlDAL : IDAL { public v ...

  8. OpenStack若干概念

    近期在部署OpenStack时涉及到各个服务之间的诸多概念,这里简要记录其中的一些作为备忘. 服务(service) 在OpenStack中,一个服务有若干端点,用户通过端点访问服务并使用服务提供的功 ...

  9. NPOI 2.1.1 系列(2) 使用NPOI读取List或者datatable数据生成 Excel文档 ;Npoi生成 xlsx 2007以上文档

    结合上一篇文章  NPOI 2.1.1 系列(1) 使用NPOI读取 Excel文档 ;NpoiExcelHelper 导入导出 2003格式 2007格式的 Excel; Npoi 导出 xlsx ...

  10. Java常量池的理解

    1.常量池的好处常量池是为了避免频繁的创建和销毁对象而影响系统性能,其实现了对象的共享.例如字符串常量池,在编译阶段就把所有的字符串文字放到一个常量池中.(1)节省内存空间:常量池中所有相同的字符串常 ...