Spring MVC与Swagger常用注解

Swagger工作原理

Swagger的核心功能之一就是通过注解来描述接口和模型，从而生成文档。
Swagger基于springfox-swagger2和springfox-swagger-ui依赖库，进行自动扫描Spring框架，并生成相应的API文档‌。
Spring MVC是Spring框架主要重要的部分，专门用于构建web应用，遵循MVC设计模式，提供了Controller、Model、View等功能模块，用于处理用户请求、调用业务逻辑层、封装数据模型和展示数据‌。
Swagger可以通过Spring MVC的注解来描述接口和模型。

主类上需要添加@EnableSwagger2注解，才能启用Swagger。

Swagger注解

主要用于定义API文档的各个方面：

• @Api: 用在控制器类上，描述API接口的信息。
• @ApiOperation: 用在控制器方法上，描述单个接口的信息。
• @ApiParam: 用在接口参数上，描述单个参数的信息。
• @ApiModel: 用在模型类上，描述数据模型的信息。
• @ApiModelProperty: 用在模型属性上，描述模型属性的信息。

Spring MVC注解

主要用于实际的请求处理：

• @Controller: 用在类上标识这个类是一个控制器。
• @RequestMapping: 用在方法或类上，定义请求的URL和方法类型。
• @RequestParam: 用在方法参数上，绑定请求参数到方法参数。
• @PathVariable: 用在方法参数上，绑定URL中的部分到方法参数。
• @RequestBody: 用在方法参数上，绑定请求体到对象。
• @ResponseBody: 用在方法上或方法参数上，表明返回的数据不是视图名称，而是返回在响应体中的数据。

在实际使用中，可以将这两种注解混合使用，以便同时从Swagger获取API文档描述和Spring MVC的请求处理功能。

Spring MVC常用注解

主要分为四类

• 控制器注解
• 请求映射注解
• 参数绑定注解
• 其他常用注解

控制器注解

@Controller
用于标记一个类作为Spring MVC的控制器。它定义了一个控制器类，但需要配合@RequestMapping使用才能真正处理请求。
@Controller用于返回页面，而@RestController，是@Controller和@ResponseBody(返回数据)的结合，最终返回的是数据，所以在访问静态页面时，需要使用@Controller注释

package org.example.mvcdemo;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
@Controller
@RequestMapping("/response")
//访问static/response(类路径)/index.html(返回页面)
public class UserController {
    @RequestMapping("demo1")
    public String method1() {
        return "/index.html";
    }
}

@RestController
这是一个组合注解，包含@Controller和@ResponseBody。它通常用于构建RESTful API，表示该控制器中的所有方法都会直接返回数据，而不是视图名称。

package org.example.mvcdemo;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @RequestMapping("/hello")
    public String hello(){//方法名称无需与@RequestingMapping括号内的名称相同
        return "Hello,Spring MVC";
    }
}

请求映射注解

@RequestMapping
用于映射Web请求到相应的处理方法上。它可以用于类或方法上，用于类时表示该类中的所有方法都会以该地址作为父路径；用于方法时则指定具体的请求路径和处理方法。

@RequestMapping(value = "/hello",method = RequestMethod.GET)//仅支持GET请求
@RequestMapping(value = "hello",method = RequestMethod.POST)//仅支持POST请求
@RequestMapping(value = "hello",method = {RequestMethod.DELETE,RequestMethod.GET,RequestMethod.POST})//支持多种请求

@GetMapping、@PostMapping、@PutMapping、@DeleteMapping等
这些是@RequestMapping的简化版，分别对应HTTP的不同请求方法（GET、POST、PUT、DELETE等）。

@GetMapping("hello")//仅支持GET请求
@PostMapping("hello")//仅支持POST请求

参数绑定注解

@RequestParam
用于获取请求参数的值。(有些特殊情况中，前端传递的参数key和后端接收的key可以不相同，@RequestParam这个注释可以来重命名参数）

package org.example.mvcdemo;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1")
     public String method1(@RequestParam(value = "name1",required = false) String name,Integer age){
        //required参数决定了name这个参数是否可以为空值，默认为true(不能为空值)
         return "name:"+name+" age:"+age;
     }
}

@PathVariable
用于获取URL中的动态部分。(主要作用于请求URL路径上的数据绑定)

package org.example.mvcdemo;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1/{name1}/{age}")
    //@PathVariable修饰的参数不能为空值
    //如果方法参数名称和需要绑定的URL中的变量名称一致，可以不用给@PathVariable的属性赋值
    //反之，如果不一致，需要给@PathVariable的属性赋值
    public String method1(@PathVariable("name1") String name,@PathVariable Integer age){
        return "name:"+name+" age:"+age;
    }
}

@RequestBody
用于将客户端发送的JSON或XML数据绑定到方法参数上。

package org.example.mvcdemo;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1")
    public UserInfo method1(@RequestBody UserInfo userInfo){
        return userInfo;
    }
}

@RequestHeader
用于获取HTTP请求头中的值。

package org.example.mvcdemo;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1")
    //获取Header的第一种方式
    public String method1(HttpServletRequest request) {
        String userAgent=request.getHeader("User-Agent");
        return userAgent;
    }
    @RequestMapping("demo2")
    //获取Header的第二种方式
    public String method2(@RequestHeader("User-Agent") String userAgent) {
        return userAgent;
    }
}

其他常用注解

@ResponseBody
用于返回数据。它既是类注解，也是方法注解，当作用在类上时，表示类中的所有方法返回的都是数据，当作用在方法上时，表示该方法返回的是数据

package org.example.mvcdemo;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
@Controller
@RequestMapping("/response")
public class UserController {
    @RequestMapping("demo1")
    @ResponseBody//method1方法返回数据
    public String method1() {
        return "/index.html";//返回字符串/index.html
    }
}

@SessionAttributes
用于在会话中保存属性，以便在多个请求之间共享数据。
存储Session

// 
package org.example.mvcdemo;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpSession;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1")
    public String method1(HttpServletRequest request) {
        //参数为true 如果session对象不存在，则创建一个session对象，反之直接返回
        HttpSession session=request.getSession(true);
        session.setAttribute("name","zhangsan");
        session.setAttribute("age",20);
        return "session设置成功";
    }
}

获取Session

package org.example.mvcdemo;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpSession;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/test")
public class UserController {
    @RequestMapping("demo1")
    //获取session的第一种方式
    public String method1(HttpServletRequest request) {
        //参数为false 如果不存在session,则返回null
        HttpSession session=request.getSession(true);
        if(session!=null){
            System.out.println(session.getAttribute("name"));
            System.out.println(session.getAttribute("age"));
        }
        return "session获取成功";
    }
    @RequestMapping("demo2")
    //获取session的第二种方式
    public String method2(HttpSession session) {
        System.out.println(session.getAttribute("name"));
        System.out.println(session.getAttribute("age"));
        return "session获取成功";
    }
    @RequestMapping("demo3")
    //获取session的第三种方式
    //与@RequestParam相同，required参数决定了name这个参数是否可以为空值，默认为true(不能为空值)
    public String method3(@SessionAttribute(value = "name",required = false) String name) {
        return "name:"+name;
    }
}

Swagger常用注解

@Api

用于类，表示这个类是Swagger的资源，通常标注在Controller上

tags：表示说明，可以替代value。如果有多个值，会生成多个list
description：对Controller进行描述

@RestController
@RequestMapping("/yang")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController {
}

@ApiOperation

用于方法，提供了丰富的属性来允许我们自定义接口的描述信息，包括接口名称和所属分组等。

value：用于方法描述
notes：用于提示内容
tags：可以重新分组（视情况而用）

@ApiOperation(value = "人员查询接口", notes = "查询描述")
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

@ApiParam

用于方法、参数、字段说明，表示对参数的添加元数据（说明或是否必填等）

name：参数名
value：参数说明
required：是否必填
allowableValues：允许的值范围

@ApiIgnore

忽略，当前注解描述的方法或类型，不生成api文档

@ApiImplicitParam

用于方法，表示单独的请求参数

name：参数名
value：参数说明
dataType：参数类型
paramType：参数类型，包括query、header、path、body、form等
example：举例说明

@ApiImplicitParams

用于方法，描述方法的一组参数

value：是@ApiImplicitParam类型的数组

@ApiImplicitParams({
    @ApiImplicitParam(name = "page", value = "当前页", required = false, dataType = "Integer"),
    @ApiImplicitParam(name = "pageSize", value = "每页显示条数", required = false, dataType = "Integer"),
    @ApiImplicitParam(name = "sort", value = "排序字段", required = false, dataType = "String")})
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

@ApiModel

用于类，表示对类进行说明，用于参数用实体类接收

value：表示对象名，可以省略
description：描述，可以省略

@Data
@ApiModel(description= "人员实体类")
public class User {
}

@ApiModelProperty

用于方法、字段，表示对model属性的说明或者数据操作更改

name：字段别名
value：字段描述
required：是否是必须字段
example：示例数据
hidden：是否隐藏数据

package com.example.test.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description= "人员实体类")
public class User {

    @ApiModelProperty(value = "姓名", required = true)
    private String name;

    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}

@ApiResponse和@ApiResponses

方法返回值的说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明

code：数字，例如：300
message：信息，例如：”请求参数没填好"
response：抛出异常的类

@ApiResponses({
        @ApiResponse(code = 200, message = "请求成功"),
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

其他注解

@Authorization：声明要在资源或操作上使用的授权方案
@AuthorizationScope：描述OAuth2授权范围
@ResponseHeader：表示可以作为响应的一部分提供的标头
@ApiProperty：描述POJO对象中的属性值
@ApiError：接口错误所返回的信息