swagger的DEMO配置@TOC
认识swagger
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
官方网址:https://swagger.io/
作用:
作用:
1. 接口的文档在线自动生成。
2. 功能测试。
配置步骤
1.需要一个有一个文件:SwaggerConfig.class
package cn.itrip.auth.controller;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@ComponentScan(basePackages = {"cn.itrip.auth.controller"})
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {
public SwaggerConfig() { }
@Bean
public Docket createRestApi() {
return (new Docket(DocumentationType.SWAGGER_2)).apiInfo(this.apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return (new ApiInfoBuilder()).title("主业务模块API").termsOfServiceUrl("http://www.itrip.com/biz").contact("0101项目组").version("1.0").build();
}
}
2.在资源配置文件application.xml加入相关代码
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:p="http://www.springframework.org/schema/p"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:task="http://www.springframework.org/schema/task"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd http://www.springframework.org/schema/task http://www.springframework.org/schema/task/spring-task.xsd">
在头部需要加入http://www.springframework.org/schema/task/spring-task.xsd这一句
底下还需要写这么一句
<mvc:default-servlet-handler />
3.在自己的corttller层的方法前面需要加入相应的swagger注解
/**
* 检查用户是否已注册
* @param name
* @return
*/
@ApiOperation(value="用户名验证",httpMethod = "GET",
protocols = "HTTP", produces = "application/json",
response = Dto.class,notes="验证是否已存在该用户名")
@RequestMapping(value="/ckusrPhone",method=RequestMethod.GET,produces= "application/json")
public @ResponseBody
Dto checkUser(
@ApiParam(name="name",value="被检查的用户名",defaultValue="15717396714")
@RequestParam String name) {
System.out.println("用户名注册名是否唯一!");
try {
if(!validPhone(name))
return DtoUtil.returnFail("请使用正确的手机注册",ErrorCode.AUTH_ILLEGAL_USERCODE);
if (null == userService.findByUsername(name)) {
return DtoUtil.returnSuccess("手机号码可用");
} else {
return DtoUtil.returnFail("手机号码已存在,注册失败", ErrorCode.AUTH_USER_ALREADY_EXISTS);
}
} catch (Exception e) {
e.printStackTrace();
return DtoUtil.returnFail(e.getMessage(), ErrorCode.AUTH_UNKNOWN);
}
}
4.运行自己的项目
在自己的项目名后面加上/swagger-ui.html
就会出现页面
常用注解解析
这里没有的注解可以参考API文档
https://github.com/springfox/springfox/blob/master/docs/transitioning-to-v2.md
@Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作 - @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等) - @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收 - @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改 - @ApiImplicitParam() 用于方法
表示单独的请求参数 - @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam