Swagger2 初始用
1.结合Spring-Boot 引入 pom 依赖
1pom.xml2 12io.springfox 3springfox-swagger2 42.9.2 56 117 10guava 8com.google.guava 913 17 18com.google.guava 14guava 1528.0-jre 1619 io.springfox 20springfox-swagger-ui 212.9.2 22
2.创建一个 SwaggerConfig 配置类
1 @Configuration 2 @EnableSwagger2 3 public class SwaggerConfig { 4 5 @Bean 6 public Docket createRestApi() { 7 return new Docket(DocumentationType.SWAGGER_2) 8 .select() 9 // 方法需要有ApiOperation注解才能生存接口文档 10 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 11 // 路径使用any风格 12 .paths(PathSelectors.any()) 13 .build() 14 // 如何保护我们的Api,有三种验证(ApiKey, BasicAuth, OAuth) 15 .securitySchemes(security()) 16 // 接口文档的基本信息 17 .apiInfo(apiInfo()); 18 } 19 20 /** 21 * 接口文档详细信息 22 * 23 * @return 24 */ 25 private ApiInfo apiInfo() { 26 return new ApiInfoBuilder().title("Swagger2 API").description("xd-api文档").termsOfServiceUrl("http://www.localhost:8080").version("1.0.0").build(); 27 } 28 29 private Listsecurity() { 30 ArrayList apiKeys = new ArrayList<>(); 31 apiKeys.add(new ApiKey("token", "token", "header")); 32 return apiKeys; 33 } 34 35 }
3.使用 controller 实例
1 @Api(tags = "登录接口") 2 @RequestMapping("/api") 3 @RestController 4 public class ApiLoginController { 5 6 @PostMapping("login") 7 @ApiOperation(value = "用户登录接口") 8 @ApiImplicitParams({ 9 @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String"), 10 @ApiImplicitParam(name = "password", value = "登录密码", required = true, dataType = "String") 11 }) 12 public String login(String username, String password) { 13 return username + " : " + password; 14 15 } 16 17 }LoginController.java
4.常用注解说明
@Api:修饰整个类,描述Controller的作用 (可选值:value,tags,description...可以自行查看源码)
@ApiOperation:描述一个类的一个方法,或者说一个接口 (用于方法;表示一个http请求的操作 ,value用于方法描述 ,notes用于提示内容)
@ApiParam:单个参数描述 (用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填(默认值为false))
@ApiModel:用对象来接收参数 (用于类 表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略)
@ApiModelProperty:用对象接收参数时,描述对象的一个字段 (用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏)
1 @ApiOperation(value = "用户发送邮件操作", httpMethod = "GET", response = String.class, notes = "用户发送邮件操作,提供用户管理-用户发送邮件操作") 2 public String sendEmail(@ApiParam ( value = "userId", required = true ) @RequestParam ( 3 value = "userId" ) String userId, 4 @ApiParam(name="邮件对象",value="传入json格式",required=true) 5 @RequestBody EmailModel model, 6 HttpServletRequest request) { 7 8 9 ------------------------------------------------------------------------------------------- 10 @ApiModel(value="邮件对象",description="邮件对象实体类") 11 public class EmailModel extends BaseModel { 12 //邮件发送人 13 @ApiModelProperty(value="邮件发送人",name="sender",example="xxxxx@qq.com") 14 private String sender; 15 //邮件接收人 16 @ApiModelProperty(value="邮件接收人",name="recipients",example="xxxxx@qq.com") 17 private String recipients; 18 //邮件主题 19 @ApiModelProperty(value="邮件主题",name="recipients") 20 private String subject; 21 //邮件内容 22 @ApiModelProperty(value="邮件内容",name="邮件内容") 23 private String text; 24 }代码段
效果图
@ApiIgnore:使用该注解忽略这个API,用于类或者方法上 (用于类或者方法上,可以不被swagger显示在页面上)
@ApiImplicitParam:一个请求参数,用于方法上
name – 参数名称
value – 参数说明
dataType – 数据类型
paramType – 参数类型
example – 举例说明
@ApiImplicitParams:多个请求参数 ,包含多个 @ApiImplicitParam,用于方法上