Swagger(初识一)

Swagger(初识一)

  • 简介
  • 配置swagger
  • 常用注解
  • 使用

简介

Swagger是一款目前世界最流行的API管理工具。目前Swagger已经形成一个生态圈,能够管理API的整个生命周期,从设计、文档到测试与部署。Swagger有几个重要特性:

  • 代码侵入式注解
  • 遵循YAML文档格式
  • 非常适合三端(PC、iOS及Android)的API管理,尤其适合前后端完全分离的架构模式。
  • 减少没有必要的文档,符合敏捷开发理念 功能强大

作用

  • 接口的文档在线自动生成
  • 功能测试

优点

  1. 大大减少前后端的沟通
  2. 方便查找和测试接口
  3. 提高团队的开发效率
  4. 方便新人了解项目

配置swagger

引入依赖

<!-- swagger -->
<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>

配置类

package com.hdt.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hdt")) //swagger搜索的包
                .paths(PathSelectors.any()) //swagger路径匹配
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文件上传文档")
                .description("使用FastDfs文件上传")
                .version("version 1.0")
                .build();
    }
}

常用注解

swagger通过在controller中,声明注解,API文档进行说明
1、@Api():用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源
参数:

tags:说明该类的作用,参数是个数组,可以填多个。
value=“该参数没什么意义,在UI界面上不显示,所以不用配置”
description = “用户基本信息操作”

2、@ApiOperation():用于方法,表示一个http请求访问该方法的操作
参数:

value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={“作用1”,“作用2”}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)

3、@ApiModel():用于响应实体类上,用于说明实体作用
参数:

description=“描述实体的作用”

4、@ApiModelProperty:用在属性上,描述实体类的属性
参数:

value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选

5、@ApiImplicitParams:用在请求的方法上,包含多@ApiImplicitParam

6、@ApiImplicitParam:用于方法,表示单独的请求参数
参数:

name=“参数ming”
value=“参数说明”
dataType=“数据类型”
paramType=“query” 表示参数放在哪里
· header 请求参数的获取:@RequestHeader
· query 请求参数的获取:@RequestParam
· path(用于restful接口) 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
defaultValue=“参数的默认值”
required=“true” 表示参数是否必须传

7、@ApiParam():用于方法,参数,字段说明 表示对参数的要求和说明
参数:

name=“参数名称”
value=“参数的简要说明”
defaultValue=“参数默认值”
required=“true” 表示属性是否必填,默认为false

8、@ApiResponses:用于请求的方法上,根据响应码表示不同响应
一个@ApiResponses包含多个@ApiResponse

9、@ApiResponse:用在请求的方法上,表示不同的响应
参数:

code=“404” 表示响应码(int型),可自定义
message=“状态码对应的响应信息”

10、@ApiIgnore():用于类或者方法上,不被显示在页面上

使用

实体类

@ApiModel("用户对象模型")
public class User {
private Long id;
private String username;
private String password;
private String email;

controller

package com.hdt.controller;

import com.hdt.bean.User;
import io.swagger.annotations.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理API")
public class UserController {
/**
 * /user post 新增
 * /{id} delete 删除
 * /{id} put 更新
 * /{id} get 根据id加载
 * /list-page post 分页查询
 */

@PostMapping
@ApiOperation(value = "新增一个用户",notes = "新增一个用户并返回一个用户")
@ApiResponses({
        @ApiResponse(code = 200, message = "返回成功", response = User.class),
        @ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),
        @ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),
})
public ResponseEntity<User>add(User user){

    if(user.getId()==1){
        return new ResponseEntity<>(user, HttpStatus.BAD_REQUEST);//400
    }
    else if(user.getId()==2){
        return new ResponseEntity<>(user,HttpStatus.UNAUTHORIZED);//401
    }
 else {
        return ResponseEntity.ok(user);
    }

}

    @PutMapping
    @ApiOperation(value = "修改用户", notes = "修改后返回当前用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "返回成功", response = User.class),
            @ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),
            @ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),
    })
    public ResponseEntity<User> update(User user) {
        if (user.getId() == 1) {
            return new ResponseEntity<>(user, HttpStatus.BAD_REQUEST); //400
        } else if (user.getId() == 2) {
            return new ResponseEntity<>(user, HttpStatus.UNAUTHORIZED); //401
        } else {
            return ResponseEntity.ok(user);
        }
    }
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "删除后返回当前id")
    @ApiResponses({
            @ApiResponse(code = 200, message = "返回成功", response = User.class),
            @ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),
            @ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),
    })
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户主键ID", required = true)
    public ResponseEntity<Long> delete(@PathVariable Long id) {
        if (id == 1) {
            return new ResponseEntity<>(id, HttpStatus.BAD_REQUEST); //400
        } else if (id == 2) {
            return new ResponseEntity<>(id, HttpStatus.UNAUTHORIZED); //401
        } else {
            return ResponseEntity.ok(id);
        }
    }
    @GetMapping("/{id}")
    @ApiIgnore
    public ResponseEntity<Long> toUpdate(@PathVariable Long id) {
        if (id == 1) {
            return new ResponseEntity<>(id, HttpStatus.BAD_REQUEST); //400
        } else if (id == 2) {
            return new ResponseEntity<>(id, HttpStatus.UNAUTHORIZED); //401
        } else {
            return ResponseEntity.ok(id);
        }
    }
    @PostMapping("/list-page")
    @ApiOperation(value = "分页查询", notes = "得到分页查询对象pageInfo")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "pageNum", value = "当前页", required
                    = false, defaultValue = "1"),
            @ApiImplicitParam(paramType = "query", name = "pageSize", value = "每页行数",
                    required = false, defaultValue = "10")
    })
    public ResponseEntity<String> findByPage(@RequestParam(defaultValue = "1", required = false)
                                                     Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) {
        return ResponseEntity.ok("find page result...");
    }



}

结果
Swagger(初识一)_第1张图片

使用swagger测试文件上传
Swagger(初识一)_第2张图片

你可能感兴趣的:(Spring,restful,java,spring,boot)