这是我参与更文挑战的第7天,活动详情查看: 更文挑战
前言
相信大家平时开发的过程中,都会使用到 API文档工具吧?大家都在使用什么呀?Java docs,I/O Docs, apiary.io, Docco, Dexy, Doxygen, TurnAPI,Swagger。今天我就来教大家如何使用 Swagger 搭建 API 文档。
什么是swagger?
- 世界上最流行的Api框架;
- RestFul Api 文档在线自动生成工具;
- 文档和实现保持同步和自动更新来简化API的构建过程;
- 直接运行,可以在线测试API接口;
- 支持多种语言:(java ,php...)
Swagger-core注解
Name | Description |
---|---|
@Api | 标记为 Swagger 资源 |
@ApiModel | 标记为 Swagger 模型 |
@ApiModelProperty | 模型字段的属性说明 |
@ApiOperation | http接口的说明 |
@ApiParam | http 接口参数说明 |
更多详细的说明可以参考 github上的解释:github.com/swagger-api…
springboot集成swagger
- 新建一个springboot项目 =>web项目
- 导入相关依赖
<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>
- 配置swagger信息
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
//根据开发环境的不同,是否开启swagger
Profiles profiles = Profiles.of("pro");
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// .enable(flag) //enable是否开启Swagger 默认是true,如果是false,则swagger不能在浏览器中
.select()
.apis(RequestHandlerSelectors.basePackage("com.cn.controller"))
.paths(PathSelectors.any())
.build();
}
public ApiInfo apiInfo(){
Contact contact=new Contact("初念初恋","https://juejin.cn/user/3940246036953293","13145200@qq.com");
return new ApiInfoBuilder()
.title("后台管理系统 API文档")
.description("越努力越幸运")
.termsOfServiceUrl("https://juejin.cn/user/3940246036953293")
.version("1.0")
.contact(contact)
.build();
}
}
- controller层
@Controller
public class LoginController {
@GetMapping(value = "/toLogin")
public String toLogin(){
return "login";
}
@ApiOperation(value = "登录")
@PostMapping("/login")
public String login(
@RequestParam("username") String username,
@RequestParam("password") String password,
Model model){
Subject subject = SecurityUtils.getSubject();
UsernamePasswordToken token = new UsernamePasswordToken(username,password);
try {
subject.login(token);
return "index";
}catch (UnknownAccountException uae){
model.addAttribute("msg","用户不存在");
return "login";
}catch (IncorrectCredentialsException ice){
model.addAttribute("msg","密码不正确");
return "login";
}
}
@GetMapping("/logOut")
public String logOut(){
return "login";
}
@GetMapping("/noAuthorization")
public String noAuthorization(){
return "未经授权,无法访问此页面";
}
}
@Controller
@RequestMapping("/userInfo")
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/userList")
public String getUserList(){
return "userList";
}
@GetMapping("/userAdd")
public String addUser(){
return "addUser";
}
@GetMapping("/userDel")
public String deleteUser(){
return "deleteUser";
}
@GetMapping("/getList")
public List<UserInfo> getList(int id){
return userService.getList(id);
}
@ApiOperation(value = "根据用户名查找用户信息")
@GetMapping("/findByUsername")
public UserInfo findByUsername(@RequestParam("username") String username){
return userService.findByUsername(username);
}
}
结尾
-
Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。
-
Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。