一、上代码
0.pom.xml
<!-- swgger 检测spring的web请求信息，生成检测结果（json格式）。 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId> <!-- 检测spring的web请求信息，生成检测结果（json格式）。 -->
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId> <!-- 根据springfox-swagger2生成的数据，生成可视化的友好页面。 -->
<version>2.9.2</version>
</dependency>
1.Swagger2Conf
@Configuration
@EnableSwagger2
public class Swagger2Conf {
@Bean
public Docket getUserDocket(){
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
parameterBuilder.name("X-Token").description("认证token") //Header里添加X-Token参数用于认证
.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
parameters.add(parameterBuilder.build());
ApiInfo apiInfo=new ApiInfoBuilder()
.title("yx-server系统")//api标题
.description("yx-server api 接口文档")//api描述
.version("1.0.0")//版本号
.build();
return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
.apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
.select()//启动用于api选择的构建器
.apis(RequestHandlerSelectors.basePackage("com.yx.controller"))//扫描接口的包
.paths(PathSelectors.any())//路径过滤器（扫描所有路径）
.build().globalOperationParameters(parameters);
}
}
2.Controller注解示例
@RestController
@RequestMapping("/user")
@Api("用户管理")
public class UserController {
@Resource
UserServicesImpl userServices;
@ApiOperation("登录")
@RequestMapping(value = "/login", method = RequestMethod.POST)
public Object login(HttpServletResponse response,
@RequestParam(value = "username", required = true) String userName,
@RequestParam(value = "password", required = true) String password) {
//用户认证信息
Subject subject = SecurityUtils.getSubject();
UsernamePasswordToken usernamePasswordToken = new UsernamePasswordToken(userName, password);
try {
//进行验证，这里可以捕获异常，然后返回对应信息
subject.login(usernamePasswordToken);
return ApiResult.success(subject.getSession().getId()); //将token返回给前端
} catch (UnknownAccountException e) {
return ApiResult.failure(ResponseCode.ACCOUNT_NOT_EXIST);
} catch (AuthenticationException e) {
return ApiResult.failure(ResponseCode.ACCOUNT_ERROR);
}
}
}
3.POJO注解示例
@Data
@ApiModel("用户")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
@JsonProperty(access = JsonProperty.Access.WRITE_ONLY) //表示 Restful接口返回给前台时不包含该字段
private String password;
@ApiModelProperty("年龄")
private Integer age;
@ApiModelProperty("生日")
@JsonFormat(pattern = "yyyy-MM-dd hh:mm:ss a", locale = "zh", timezone = "GTM+8")
private Date birthday;
@ApiModelProperty("描述")
private String des;
}
二、访问swagger
image.png
三、 常用注解说明
swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。
@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误的返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数
更多使用说明，参考 Swagger 使用手册。
