Swagger

Swagger

WebService提供了WSDL来描述提供的WS调用接口,还提供了其它工具来生成WS客户端代码。REST则可以使用Swagger规则来描述Restful接口,以及通过Swagger UI来测试Restful接口。

Swagger2是通过在接口上提供一系统注解来描述接口,而Swagger3则是通过一个swagger规范的json文件来描述。

Swagger使用指南
https://my.oschina.net/dlam/blog/808315
swagger2常用注解说明
https://blog.csdn.net/u014231523/article/details/76522486

Spring boot项目,使用maven打包包含本地jar
http://www.jianshu.com/p/4f88837945c9

swagger2markup

1.单独启动要输出文档的swagger服务。
2.在@Test中编写Swagger2MarkupConverter部分代码,或在pom.xml中配置。
3.运行mvn test,生成.adoc文件。
4.在Maven视图中,运行Plugins下的asciidoctor:process-asciidoc,生成html文件。
http://blog.didispace.com/swagger2markup-asciidoc/

Swagger 2.9.2

出现Unable to infer base url,java.lang.NumberFormatException: For input string: “”错误,解决方法:在@ApiImplicitParam中增加 example参数值。
并且 2.9.2版本界面风格也发生了变化,需要点击 Try it out,再执行 Execute。

注解

@ApiIgnore 或 @ApiParam(hidden = true) 加在参数前,可以使用参数不被显示在swagger ui中。

带附件的接口

只在附件参数前加@ApiParam注解,或者只添加@RequestBody注解,但没有字段注释。

@ApiOperation(value = "注册用户", notes = "")
@ApiImplicitParams({
        @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", dataType = "string", required = false),
        @ApiImplicitParam(name = "mobilePhone", value = "手机号", paramType = "query", dataType = "string", required = true)
})
@RequestMapping(value = "/registUser", method = RequestMethod.POST)
ResponseProto registUser(String mobilePhone, String userName,@ApiParam(value = "头像", required = true) MultipartFile image) {
}

发表评论