Swagger简介
导语:
前后端经常存在因为接口文档难以维护、沟通不及时而影响开发效率。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用
- 在线生成API文档
- 功能测试,类似postman
使用步骤:
-
导入maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
-
配置swagger
@Configuration @EnableSwagger2 public class Config { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket docket(){ //设置要显示的swagger环境 Profiles profiles = Profiles.of("dev","test"); //判断是否处在自己设置的环境种 boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) //是否开启swagger .enable(true) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.ghe.springbootshiro.controller")) .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("更多请关注https://www.cnblogs.com/shuxiansheng/") .termsOfServiceUrl("https://www.cnblogs.com/shuxiansheng/") .contact(new Contact("贺国健","https://www.cnblogs.com/shuxiansheng/","a19917117294@163.com")) .version("2.0") .build(); } }
-
swagger的注解使用
@Controller //本controller的功能描述 @Api(value = "简书-演示",description = "用来演示Swagger的一些注解") public class MyController { //option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其他可以忽略 @ApiOperation(value="登录首页", notes="登录首页") //这里是显示你可能返回的http状态,以及原因。比如404 not found, 303 see other @ApiResponses(value = {@ApiResponse(code = 404, message = "页面走丢了", response = Void.class),@ApiResponse(code = 401, message = "未授权", response = Void.class) }) @RequestMapping({"/","/index"}) public String index(Model model){ model.addAttribute("msg","hello shiro!"); return "index"; } }
如何配置多个分组group?
配置多个
@Bean
public Docket docket(){}即可
如何关联到实体类?
在扫描的Controller中返回实体类
//只要扫描的接口中返回实体类,他就会被扫描到swagger
@RequestMapping("/user")
public User1 user1(){
return new User1();
}
@Data
@AllArgsConstructor
@NoArgsConstructor
//类功能描述
@ApiModel("用户类")
public class User1 implements Serializable {
//字段说明
@ApiModelProperty("用户id")
private int id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("用户权限")
private String permiss;
}
swagger注释:
@ApiOperation:给控制类添加注释
@ApiParam(“用户名”): 给方法参数添加注释
@ApiModel(“用户类”): 给实体类添加注释
@ApiModelProperty(“用户id”): 给实体类的字段添加注释
@ApiOperation("用户登录,需要参数")
@RequestMapping("/toLogin")
public String loginService(@ApiParam("用户名") @RequestParam String username, @ApiParam("密码") @RequestParam String password,Model model){
总结:
-
我们可以通过swagger给一些难以理解的方法或者属性添加注释
-
swagger实时更新
注意:
- 在项目上线后关闭swagger
rname, @ApiParam(“密码”) @RequestParam String password,Model model){
- 在项目上线后关闭swagger
总结:
- 我们可以通过swagger给一些难以理解的方法或者属性添加注释
- swagger实时更新
注意:
- 在项目上线后关闭swagger
- 关闭swagger可以节省内存