首先还是引用相关jar包。我使用的maven,在pom.xml中引用相关依赖(原来我使用的是2.2.0的,现在使用2.4.0的):
第二步就是创建swagger的配置类:
这个配置类和springmvc的写法完全一致。为了区分我又重命名一个。
在原来2.2.0的版本中使用new ApiInfo()的方法已经过时,使用new ApiInfoBuilder()进行构造,需要什么参数就添加什么参数。当然也可以什么都添加。如:
那么页面显示的效果如图:
使用new ApiInfoBuilder().build();
点击ApiInfoBuilder.java的源码可以看到相关方法使用。
第三步就是在自己的controller添加相关的注解:
原来使用在类上使用@controller,现在可以使用@RestController,然后方法的@ResponseBody就可以不用写了,因为@RestController的注解接口上已经添加了,要求版本在4.0.1之后。
常用注解:
- @Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作
- @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
- @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
- @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
具体使用举例说明:
@Api()
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
下面会用代码和示例图说明。
第四部就是在启动项目在浏览器上输入url:
http://{ip}:{port}/swagger-ui.html#/
我在application.properties中设置的自己的端口号为9090(如果不设置,默认为8080)
这里会把相应包下的所有controller按类进行显示。
我们看下其中一个类UserController.java,(请忽略业务逻辑,只看注解)
这里说明下,在使用对象作为参数时,可以在对象上添加相应的注解,用户页面显示。
如:
- 这个是对象参数时,swagger-ui要用json写
看上图红框的部分,其中一个是json格式的点击就可以获取参数格式。
第二张中可以看到字段相应的注释和是否必填。
如果在字段上添加注释@ApiModelProperty(required=true)就是必填(默认是false),相应的页面optional标识也会消失,标识这个字段必填。
点击下面的try it out按钮就可以进行调试。
- 在使用单个参数时,对应的效果图如下: