springfox/swagger生成api文档

最近的工作内容是做一个后端系统,对前端提供web接口。前后端使用类似restful的api。系统并没有完全使用restful的规范,而是简化为客户端post一段json上来,所有参数都放里面,后端解析后再做处理。

由于两端需要沟通,制定一个统一的接口文档就非常重要。放狗搜了一下,先是选择了swagger。发现略坑,然后搜到springfox,它整合了swagger,提供各种工具。就它了。

由于以前没用过springfox,零零碎碎花了两天时间才搞好。由于项目并没有用springboot也不是普通的那种通过url传参的springmvc,项目是自己用jackson做反序列化,并不是通过配置让spring自动去做,springfox并不支持这种不常见的方式,但已不是项目初期,修改的工作量挺大,最后只好决定把请求参数的对象放到返回参数去,正常的返回参数放200,请求的放201.

要注意的地方:

  1. web.xml需要添加swagger的servlet然后做urlmapping,不然swagger-ui.html和/v2/api-docs显示不出来。
  2. swagger的配置文件要加一个swagger config的bean。
  3. swagger config类是做定制化显示用的。例如版本号,作者信息等等。通过实现多个Docket可以输出多条api路径信息和接口文档。
  4. 使用springfox-staticdocs可实现输出静态api文档。但是有个坑,默认编码并非utf-8,中文会乱码。只好自己实现一个Swagger2MarkupResultHandler,在里面指定编码格式。已提pr,不知他们接不接受。

整个项目示例项目在这里

下一步可以打算开始做自动化api测试了。这篇文章给了我不少启发。

发表在 技术 | 标签为 , , , | 留下评论

骑行珠海(下)

第三天了,早上8点一起在前台退房然后就去吃早饭,吃了个还不错的小笼包。聪少说要为路上准备一些干粮,自告奋勇的带路去了附近一家面包店,大家看他兴冲冲的样子就知道肯定有D野。果不其然,去到面包店,他一直在色迷迷的盯着收银的妹纸,大家都买好干粮了还不肯走,土豪金只好硬把他拖了出店,他还说时间还早不急着出发。青哥说你看我们来的时候骑了好久,现在还不出发那可能得要凌晨才能回到,聪少说:不怕,我们骑车回程会快很多的,因为永日英勇的选择了坐广珠城轨啊。

在来的路上,永日就一直在怂恿我陪他一起坐城轨回广州,特别是今天,他动用了他的嘴炮功夫试图打动我们,我摸摸自己的菊花,也曾动摇过,但是不能啊,就这么灰溜溜的回去,给别人知道了多丢脸啊。我毅然拒绝了。

昨天聪少临时决定不走来时路,回去的时候走S111省道,我只好祭出NEXUS7打开GOOGLE MAP查找路线,看起来路程和G105差不多,永日去珠海北也顺路。过后才知道S111比G105要崎岖得多,因为长的桥好多,上坡下坡的把人累个半死。地死早啊。S111珠海段的风景不错,一直沿着海边走,感觉很好。骑了一段不见了永日踪影,只好停下来等他。抽了半包烟,他终于来了,一下车就投诉说车不行,“怎么走下坡路的时候车会自己停呢”。聪少只好帮他检查,发现车没问题,“哎呀!”,聪少一拍脑瓜,“尼玛!这一路骑过来都是上坡好不好啊?”

终于到了分叉路口,城轨向右,骑车向左。永日还在做最后的努力,我们没让他得逞。省道比国道要窄,要破烂得多,一路上几乎都是直路,但也有好几次走错了路,幸好有GOOGLE MAP指点方向。快过了中山的时候,土豪金和青哥开始感觉气不是很顺,好像有东西堵着喉咙,图样图森破。过了中山就到了南沙了,路开始宽,人很少,一副厂区的景象。我们顺着番禺大道一直到迎宾路再转去洛溪大桥方向,回到G105。我和他们在上洛溪大桥前就分道扬镳了,因为高佬说请我去吃鱼生。鱼生不错,老板娘也年轻又漂亮,赞。

吃完饭就继续往工业大道方向骑,过人民桥走康王路,回到来大概11点多了。放好单车一看里程表,316KM。

The End.

发表在 旅行 | 留下评论

Nokia的一首铃声”Listen”

个人觉得很不错

发表在 生活 | 留下评论

骑行珠海(中)

睡醒已是快10点,赖一会床,肚子开始饿了。之前聪少有电话叫我们去吃早餐我们想歇多一会没去,所以就只和永日一起下去吃BRUNCH了。电梯口碰到两个妹纸,算不上国色天香但也挺耐看的,一起进电梯的时候永日流了一地的口水,见我笑他,忙说是肚子饿的缘故。想想也是,他全身就剩右手还能用,也就只能联想一下了。

酒店在海岸边附近,这两天又是在搞神马音乐节,所以PEOPLE MOUNTAIN PEOPLE SEA,本想去一家茶餐厅医肚,细想之下还是算了,从拿筹到下单上菜,没有个把两个小时是搞不定的了,只好折返到酒店对面的街上,去了全国餐厅三大品牌之一的沙县小吃点了个鸡腿饭和撸肉饭。吃完过马路,我说我们从右边回酒店吧,永日不依,说左边应该有小路上去,近点。走了几步才发现刚才那两个妹纸在路边不知是等人还是等车,再走几步发现我被他坑了,那边根本没路回去,无奈只好折返,那两个妹纸还在。我了个去,永日你要是想看多几眼就直说啊,何必要我陪你一起走冤枉路。永日解释他第二次流口水的原因是沙县的撸肉饭很好吃,在回味中。

回到酒店大家都把昨晚没时间洗的衣服都洗了挂抽风机下晾好然后就午睡了。

睡醒已是4点多,聪少提议骑车去附近一个叫野狸岛的地方走走。沿着情侣路一直走,两边都是汹涌的人潮,好不容易才去到小岛,在岸边歇息的时候,聪少被永日抓拍到一张带着浓浓的基情味的私密照片,这里就不贴上来了。天色开始暗了,大家决定去酒店附近的强记湛江鸡吃饭,味道还不错。匆匆吃完就会酒店看恒大对柏太阳神的比赛了,4比0,挺爽的。郜飞机继续打飞机,三个外援继续包办4个进球。

看完球赛都10点了,聪少神秘兮兮的跑来我们房间说大家骑车这么累不如去按按脚什么的,为明天的回程做准备,特别是永日。 永日听了非常兴奋,我说:你不是决定坐城轨回广州吗?永日不说话了。酒店就有足浴的服务,服务员太少,我们只好在一个房间里边看电视边等,期间聪少问了好几次服务员是不是女的,得到了肯定的答复他就不说话了。有一个服务员有空了,因为房间太小只能容3个人洗脚,我和永日就去了另外一个房间,可能是服务员不大对他的胃口,他假意让我先洗,我就无所谓反正谁都一样。服务员一边给我的盆子倒热水一边说:可能要等一个小时才再有服务员来,怂恿永日做另外一种服务,那种服务员多。永日假意推辞说银两不足,跟我要了房卡说回屋去了。

这个服务员是个话痨,一直在说自己的事情,说男朋友骗了她几万块钱溜了,说自己还是很想他之类的,我安慰她说:不要在意这些细节。按完了浑身有点痛,但肌肉感觉是好点了。结帐完了就去找聪少他们仨,他们也快好了。聪少说永日留了房卡在他那里后就不知道去了哪里了。我们走回房的时候,发现原来永日在聪少房间和聪少的骑友(他没去足浴)在聊天,我们问他刚才去哪了,他说和我们一样去足浴了。嗯,大家懂的。自此我们的永日叔叔就多了个外号:宝剑侠。

发表在 旅行 | 留下评论

骑行珠海(上)

10月1号早上5点半左右在客村集合,6个好基友,在准备一点都不充分的情况下,沿着G105国道浩浩荡荡的出发了。刚过了洛溪桥,永日叔叔的后轮爆胎了,当时才7点,修车铺没这么早开门,还好聪少带多了一条备胎(字面意思别误会),在我的中学时期自己修车补胎的经验的指导下,聪少帮永日换好了后胎,耗时两小时。9点继续前进,刚过了长隆的门口,永日叔叔的后胎又爆了,经检查发现外胎吃了一块薄铁片。唉,毕竟图样,竟然第一次换胎竟然没检查外胎。备胎没了,经我们4人研究决定,派聪少回头找修车铺买备胎回来现场再换。在烈日曝晒下等了半个多小时,聪少带着3条内胎回来了。有了第一次的经验,补胎顺利了很多。

继续出发,去到顺德,汇合另外一个在那里等的朋友,又出发了。过了不到一个小时,永日叔叔开始有反应了(别误会),他说开始头晕浑身乏力。经我们5人研究决定,继续派聪少去买瓶风油精回来,聪少的一个朋友“土豪金”大方的开了两瓶葡萄糖口服液给永日服用。就在大家等永日恢复的当口,聪少的另外一个朋友平哥的后胎又吃了一条细铁条,经我们5人研究决定,还是派聪少原地帮平哥换胎。因为到饭点了,我们几个就往前走,找小饭馆去了。

顺德的小饭馆做的菜还不错,大家都赞不绝口。休整了一会,两点半了,继续出发。

永日叔叔的状态还是不怎么样,我们怕他临阵脱逃,经他们5人研究决定派我看着永日叔叔,监督他继续前进。他们4个就在前面骑,距离越拉越远了。永日叔叔好几次想借着上厕所的机会遁逃,被我机智的识破了,图森破!就这样半走半停的,时间过得好快,8点多就到了中山詹园附近了,聪少4人已开好位置等我和永日吃饭了。还好老板娘姿色不错,永日又恢复了一点点元气。

晚上9点半继续出发,这才是噩梦的开始。好不容易把永日连哄带骗的带到了中山珠海边界,聪少竟然说不知道怎么去酒店。如果眼神能杀人的话,永日已经被判了几千年的徒刑了。无奈之下我打开了GOOGLEMAP,按图索骥,长途跋涉,终于在晚上11点多12点的时候入住酒店了。永日说,除了他平时每天都在不停锻炼的右手,全身其他地方都在痛。

一夜无话。

发表在 旅行 | 留下评论