生成接口文档的工具有很多种,这里我使用了Swagger。
使用工具:idea、maven、springboot、swagger,相关知识参考:swagger官网https://swagger.io。
springboot项目使用swagger有两种方法,一种直接使用第三方依赖,这是最简单的(我这里没有尝试),可以参考https://github.com/SpringForAll/spring-boot-starter-swagger,我使用的是第二种使用官方依赖,如下:
1.引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2.spring的swagger配置,主要是把basePackage设置到需要生成文档的package上。
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo2.business.basic"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格")
//.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
3.对http://localhost/swagger-ui.html的资源在webconfig中做一些处理,因为这个页面会访问maven引入的jar中的js\css等资源,否则会报404错误,或者无法正确显示该页面。
package com.example.demo2.config;
import com.example.demo2.sysInit.LoginHandlerInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;
@Configuration
@EnableWebMvc
public class webConfig implements WebMvcConfigurer {
@Bean
public LoginHandlerInterceptor getLoginHandlerInterceptor() {
return new LoginHandlerInterceptor();
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
LoginHandlerInterceptor loginHandlerInterceptor=new LoginHandlerInterceptor();
//添加忽略路径
registry.addInterceptor(loginHandlerInterceptor).addPathPatterns("/**")
.excludePathPatterns("/login","/submit","/static/**","swagger-ui.html","webjars/**");
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//swgger访问引用的jar中的文件,需要对路径进行转换
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
//将所有/static/** 访问都映射到classpath:/static/ 目录下
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
}
}
4.controller添加swagger注释,测试
package com.example.demo2.business.basic.controller;
import com.example.demo2.business.basic.service.GaodeMapService;
import com.example.demo2.business.basic.service.UserService;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
/**
* 用户控制器
*/
@RestController
@RequestMapping("web/user")
public class UserController {
@Autowired
private UserService userService;
/*
* @Desciption: 查询昵称是否重复
* @param nick 昵称
* @Return: java.lang.String
* @Author: ada
* @Date: 2020/2/18 21:01
* @Version: 1.0
*/
@GetMapping("checkNick/{nick}")
@ResponseBody
public String checkNick(@PathVariable("nick") String nick){
if(StringUtils.isEmpty(nick.trim())){
return "查询的昵称不能为空";
}
Boolean isFalg=userService.isExistNick(nick.trim());
if(isFalg){
return "201";
}
return "200";
}
/*
* @Desciption: 查询登录账号是否重复
* @param uin 登录账号
* @Return: java.lang.String
* @Author: ada
* @Date: 2020/2/18 21:01
* @Version: 1.0
*/
@GetMapping("checkUin/{uin}")
@ResponseBody
public String checkUin(@PathVariable("uin") String uloginName){
if(StringUtils.isEmpty(uloginName.trim())){
return "查询的登录账号不能为空";
}
Boolean isFalg=userService.isExistLoginName(uloginName.trim());
if(isFalg){
return "201";
}
return "200";
}
/*
* @Desciption: 用户注册
* @param uNickName 昵称
* @param uLoginName 登录账号
* @param pwd 登录密码
* @param tel 手机号码
* @Return: java.lang.String 201:昵称或账号不可注册 202:四个参数中间存在空 203 添加失败,程序异常 200 成功
* @Author: ada
* @Date: 2020/2/19 23:30
* @Version: 1.0
*/
@PostMapping("/")
@ResponseBody
public String register(@RequestParam("nick") String uNickName,
@RequestParam("uin") String uLoginName,
@RequestParam("pwd") String pwd,
@RequestParam("tel") String tel){
if(StringUtils.isEmpty(uNickName) || StringUtils.isEmpty(uLoginName) || StringUtils.isEmpty(pwd) ||
StringUtils.isEmpty(tel)){
return "202";
}
//查询账号 昵称是否重复
if(userService.isExistNickOrLoginName(uNickName,uLoginName)){
return "201";
}
boolean falg=userService.addUser(uNickName,uLoginName,pwd,tel);
if(falg){
return "200";
}
return "203";
}
}
5.打开http://localhost/swagger-ui.html,这里项目端口为80,所以端口没有显示