Swagger接入
一 简介
Swagger是一个开源项目,用于描述和生成RestAPi的文档。可以帮助开发人员快速了解web服务的功能。
二 接入Swagger流程
1.在所在Module的pom.xml中,添加Swagger annotation 依赖
<dependency> <groupId>com.wordnik</groupId> <artifactId>swagger-annotations</artifactId> <scope>compile</scope> <version> 1.5 . 1 -M2</version> </dependency> |
2.在classpath:/templates/目录,添加swagger maven plugin需要的模板templates.zip
3.在Controller所在Module的pom.xml文件中配置swagger maven plugin
<plugin> <groupId>com.swagger.test</groupId> <artifactId>swagger-maven-plugin</artifactId> <version> 3.0 . 5 </version> <configuration> <enable>${doc-enable}</enable> <!--注意这里 --> <apiSources> <apiSource> <springmvc> true </springmvc> <!--是否spring mvc项目,我们的项目都填是 --> <locations>com.swagger.web</locations><!--Controller所在包 --> <schemes>http</schemes><!--协议 --> <host></host><!-- 服务器地址,空值表示跟文档是同一台机器(域名) --> <basePath>/test</basePath><!-- api url 前缀 --> <info> <title>test API</title><!-- Api 标题啊 --> <version>v1</version><!-- Api版本 --> <description>test API的详细描述</description><!-- Api的详细描述 --> <termsOfService> http: //www.test.com </termsOfService> <contact> <email>123 @qq .com</email><!-- 联系人邮件 --> <name>yourname</name><!-- 联系人姓名 --> </contact> </info> <templatePath>classpath:/templates/strapdown.html.hbs</templatePath><!-- 文档模板 --> <outputPath>${basedir}/src/main/webapp/doc/document.html</outputPath><!-- 文档输出路径,设置在和SwaggerUI同一目录 --> <swaggerDirectory>${basedir}/src/main/webapp/doc/</swaggerDirectory><!-- Swagger.json输出路径,设置在和SwaggerUI同一目录 --> </apiSource> </apiSources> </configuration> <executions> <execution> <phase>compile</phase> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> |
其中,enable如果设置为true的话,就会一直生成文档,如果想分环境设置的话,可以在profile里配置doc-enable变量属性实现
<profiles> <profile> <id>local</id> <activation> <activeByDefault> true </activeByDefault> </activation> <properties> <conf-dir>local</conf-dir> <doc-enable> true </doc-enable> </properties> </profile> </profiles> |
4.将Swagger UI添加到项目的web目录下swagger_ui.zip,修改index.html文件第29行
url = "/jingquadmin/doc/swagger.json" TO url = "/yoururl/doc/swagger.json"
(另,附件中的document.html和swagger.json是插件swagger maven plugin自动生成的,添加与否均可)
(添加Swagger UI,主要是为了API的可视化)
5.在Controller上添加API annotation,在Controller接口上添加Swagger annotation
6.maven编译项目,然后启动项目或plus发布项目,链接如下:
http://host/basepath/doc/index.html 自动测试平台
http://host/basepath/doc/document.html API文档
三 Swagger常用注解介绍
|
|
|
---|---|---|
annotation
|
说明
|
属性介绍
|
Api | 加在Controller类上,将Controller标记为Swagger资源 |
value - 名称 description - 描述 |
ApiOperation | 加在Controller方法上,表明这个方法是一个rest接口,一个@Api下可有多个@ApiOperation(一个Controller文件可有多个接口) |
value - 接口名称 notes - 详细描述 response - 返回类 |
ApiImplicitParams/ApiImplicitParam/ApiParam | 加在Controller方法上,表明这里需要隐藏的参数 |
name - 参数名 value - 参数描述 defaultValue - 默认值 required - 是否必需 dataType - 数据类型 |
ApiModel | 加在Model类上,用来描述封装的参数对象和返回的参数对象 | description - 描述 |
ApiModelProperty | 加在Model类的属性上,描述参数的对象属性 |
value - 属性描述 |
完整Annotation详见http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html
其他:
SpringMVC项目也可以通过接入Springfox来自动生成API文档,Springfox的前身是swagger-SpringMVC,一个开源的API doc框架。
注意:
在Controller文件中定义接口时,@RequestMapping注解中的method属性是必须要设置的,否则Swagger插件不会生成对应接口信息;
@RequestMapping(value = "/v2/group", method = RequestMethod.GET)
*内部人员(绿山墙注)
Swagger接入的更多相关文章
- ASP.NET Core Swagger接入使用IdentityServer4 的 WebApi
写在前面 是这样的,我们现在接口使用了Ocelot做网关,Ocelot里面集成了基于IdentityServer4开发的授权中心用于对Api资源的保护.问题来了,我们的Api用了SwaggerUI做接 ...
- 接口文档神器Swagger(下篇)
本文来自网易云社区 作者:李哲 二.Swagger-springmvc原理解析 上面介绍了如何将springmvc和springboot与swagger结合,通过简单配置生成接口文档,以及介绍了swa ...
- Asp.Net Core SwaggerUI 接入
Asp.Net Core SwaggerUI 接入 简单了解 swagger的目的简单来说就是,不用为每个接口手动写接口文档,因为它是根据接口自动生成的,接口更改时文档也同步更新,减少了手动更新的麻烦 ...
- swagger在线api文档搭建指南,用于线上合适么?
在上一篇文章中,我们讲解了什么是 api,什么是 sdk: https://www.cnblogs.com/tanshaoshenghao/p/16217608.html 今天将来到我们万丈高楼平地起 ...
- [Abp vNext 入坑分享] - 6.完整接入swagger
前言 由于最近一直在修改一下排版,同时找了非技术的朋友帮忙看一下排版的问题,现在已经基本上确定了排版和样式了.更新可以恢复正常了. 作为一个写前端代码基本只写js不写css的开发,搞排版真的头疼..各 ...
- Asp.Net Core WebApi中接入Swagger组件(初级)
开发WebApi时通常需要为调用我们Api的客户端提供说明文档.Swagger便是为此而存在的,能够提供在线调用.调试的功能和API文档界面. 环境介绍:Asp.Net Core WebApi + S ...
- WebApi接入Swagger
1.新建webApi项目 2.nuget引入 swagger 3.在项目属性里配置输出 xml文件 4.打开SwaggerConfig.cs编辑 protected static string Get ...
- spring接入swagger后单元测试报错
2017-05-16 11:58:05.276 INFO 11268 --- [ main] s.c.a.AnnotationConfigApplicationContext : Refreshing ...
- net core体系-API-Restful+Swagger搭建API
本篇主要简单介绍下.net core下搭建WebApi 项目结构 项目结构其实不用多说,基本上大同小异. Controller:对外暴露的契约 Business/IBussiness:业务逻辑层实现及 ...
随机推荐
- [数据库事务与锁]详解八:底理解数据库事务乐观锁的一种实现方式——CAS
注明: 本文转载自http://www.hollischuang.com/archives/1537 在深入理解乐观锁与悲观锁一文中我们介绍过锁.本文在这篇文章的基础上,深入分析一下乐观锁的实现机制, ...
- atitit.vod search doc.doc 点播系统搜索功能设计文档
atitit.vod search doc.doc 点播系统搜索功能设计文档 按键的enter事件1 Left rig事件1 Up down事件2 key_events.key_search = fu ...
- Python - 动手写个ORM
Python - 动手写个ORM 任务: 模拟简单的ORM - Object Relational Mapping 为model添加create方法 代码很简单,直接上 字段类型类 class Fie ...
- CCNA网络工程师学习进程(3)常规网络设计模型与基本的网络协议
本节介绍分层的网络设计模型与基本的网络协议,包括ARP协议,ICMP协议和IP协议. (1)三层网络架构: 一个好的园区网设计应该是一个分层的设计.一般分为接入层.汇聚层(分布层).核 ...
- struts之动态方法调用使用通配符
一.DMI动态方法调用的其中一种改变form表单中action属性的方式已经讲过了.还有两种,一种是改变struts.xml配置文件中action标签中的method属性,来指定执行不同的方法处理不同 ...
- iOS开发中 workspace 与 static lib 工程的联合使用
在iOS开发中,其实workspace的使用没有完全发挥出来,最近做了一些研究,也想把之前写过的代码整理下,因为iOS里面的布局方式,交互方式也就那么几种.所以,整理好了之后,更能快捷开发,而且能够形 ...
- 分享一个 C# Winfrom 下的 OutlookBar 控件的使用
最近在上网的时候,发现了这个C# 下的 OutlookBar 控件,看了一下感觉还真不错,特此记录一下. using System; using System.Drawing; using Syste ...
- 有关try..catch..finally处理异常的总结
//看一下下面的程序,你能正确的写出不同的testEx2()方法时,程序的最终打印出来的数据吗....先不要看下面的答案 public class ExceptionTest { public Exc ...
- java中异常注意问题(发生在多态是的异常问题)
/* 异常的注意事项: 1,子类在覆盖父类方法时,父类的方法如果抛出了异常,那么子类的方法只能抛出父类的异常或者该异常的子类. 2,如果父类抛出多个异常,那么子类只能抛出父类异常的子集. 简单说:子类 ...
- 《BI那点儿事》Microsoft 决策树算法——找出三国武将特性分布,献给广大的三国爱好者们
根据游戏<三国志11>武将数据,利用决策树分析,找出三国武将特性分布.其中变量包括统率.武力.智力.政治.魅力.身分.变量说明:统率:武将带兵出征时的部队防御力.统帅越高受到普通攻击与兵法 ...