swagger

Swagger简介

导语：

前后端经常存在因为接口文档难以维护、沟通不及时而影响开发效率。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用

1. 在线生成API文档
2. 功能测试，类似postman

使用步骤：

1. 导入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>
   

2. 配置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();
       }
   }
   

3. 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可以节省内存