swagger2的简单使用

swagger2的简单使用

优点:
可以生成文档形式的API并提供给不同的团队使用

便于自己单测

无需过多冗余的word文档,这一点很重要,因为我在工作中就遇到这么一个情况,由于开发使用的文档和最新文档版本导致不一致,导致后期很烦人

=使用swagger流程=

1.引入pom依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

2.新建swagger2配置类

new class Swagger2

@Configuration //使用配置类注解
@EnableSwagger2 //启用这个配置类
public class Swagger2 {
	/**
	 * @Description:swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
	 */
	@Bean //配置这个bean是为了让swagger扫描到controller
	public Docket createRestApi() {
		
		// 为swagger添加header参数可供输入  
//        ParameterBuilder userTokenHeader = new ParameterBuilder();
//        ParameterBuilder userIdHeader = new ParameterBuilder();
//        List<Parameter> pars = new ArrayList<Parameter>();
//        userTokenHeader.name("headerUserToken").description("userToken")
//        	.modelRef(new ModelRef("string")).parameterType("header")
//        	.required(false).build();
//        userIdHeader.name("headerUserId").description("userId")
//	    	.modelRef(new ModelRef("string")).parameterType("header")
//	    	.required(false).build();
//        pars.add(userTokenHeader.build());
//        pars.add(userIdHeader.build());
		
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.csylh.controller"))
				.paths(PathSelectors.any()).build();
//				.globalOperationParameters(pars);
	}

	/**
	 * @Description: 构建 api文档的信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 设置页面标题
				.title("swagger2构建接口数据文档,这里是文档的标题")
				// 设置联系人
				.contact(new Contact("留歌", "http://csylh.cn", "csylh36@163.com"))
				// 描述
				.description("留歌短视频,这里是描述信息")
				// 定义版本号
				.version("V-1.0").build();
	}

}

3.配置controller类,方法和实体类

3.1对于某一个Controller添加一个API====@Api

@Api:用在请求的类上,表示对类的说明
- tags=“说明该类的作用,可以在UI界面上看到的注解”
- value=“该参数没什么意义,在UI界面上也看到,所以不需要配置”
案例:
@Api(value = “用户注册登录接口”,tags = {“登录注册注销的controller”})
public class UserController{}

3.2对于Controller不同的接口(方法)进行定义==@ApiOperation

@ApiOperation:用在请求的方法上,说明方法的用途、作用
- value=“说明方法的用途、作用”
- notes=“方法的备注说明”
案例:
@ApiOperation(value = “用户注册接口”, notes=“这是用户注册的接口,随便写都可以”)
public ServerResponse register(@RequestBody Users user){
return iUserService.register(user);
}

接下来对方法参数情况进行分类

情况一:(String userId,String fanId)参数场景

方法参数的问题:上面的是@RequestBody这样的场景,有的时候就是一个个参数 (String userId,String fanId)
我们就可以使用@ApiImplicitParams来定义参数
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- name:参数名
- value:参数的汉字说明、解释
- required:参数是否必须传
- paramType:参数放在哪个地方
header --> 请求参数的获取:@RequestHeader
query --> 请求参数的获取:@RequestParam
path(用于restful接口)–> 请求参数的获取:@PathVariable
body(不常用)
form(不常用)
- dataType:参数类型,默认String,其它值dataType=“Integer”
- defaultValue:参数的默认值
案例:
@ApiOperation(value=“用户头像上传”, notes=“用户头像上传接口”)
@ApiImplicitParam(name=“userId”, value=“用户id”, required=true,
dataType=“String”, paramType=“query”)
public ServerResponse uploadIcon(String userId,@RequestParam(“file”) MultipartFile[] files) throws IOException {
return iUserService.uploadIcon(userId,files);
}

情况二:参数是使用@RequestBody这样的场景

上面这样基本配置之后其实也是可以进行运行的,但是我们更好的是可以对传入的users参数做一些限制,例如,传入的username参数字段不能为空等
操作: 跟进Users这个实体类进行配置

因为Users是一个实体,所以就要定义为@ApiModel

@ApiModel:用于响应类上,表示一个返回响应数据的信息
这种一般用在post创建的时候,使用@RequestBody这样的场景
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
案例:
@ApiModel(value = “用户对象,这里是解释”,description = “这是用户对象,这里是描述”)
public class Users {}

实体类上字段的处理

=前端必须传入过来的字段情况=@ApiModelProperty

//用户名字段
@ApiModelProperty(value = "用户名",name = "username",example = "liuge36",required = true)
private String username;
//前端传过来的密码字段
@ApiModelProperty(value = "密码",name = "password",example = "123456",required = true)
private String password;

====前端不需要传入过来的字段情况,不需要显示 @ApiModelProperty(hidden = true)
@ApiModelProperty(hidden = true)
private String id;
这样就不会显示出来了

===到这里,基本的使用就到位了,后期有机会跟新更多swagger2的用法
补充:定义包扫描
@MapperScan(basePackages=“com.csylh.mapper”)

posted @ 2018-10-09 10:28  liuge36  阅读(113)  评论(0编辑  收藏  举报