swagger2怎么使用以及常用注解

一、怎么使用swagger2

1、首先导入依赖

<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <version>2.3.7.RELEASE</version>
    </dependency>
    <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、创建一个启动类，然后跑一下启动类
然后本地访问http://localhost:8080/swagger-ui.html

能够访问成功就说明可以了，是不是很简单

二、常用注解

1、@Api

@Api是类上注解，控制整个类生成接口信息的内容
参数的tags则表示类的名称，这个可以有多个值可以表示多个副本
代码和和具体效果在下面：

package org.example.controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author weiguorong
 * @date 2021/2/13 19:33
 */
@RestController
@Api(tags = {"mydemo","mycontroller"})
public class MyController {

    @GetMapping("/get")
    public String get(String a,String b){
        return "get";
    }

    @PostMapping("/post")
    public String post(){
        return "post";
    }

    @RequestMapping("req")
    public String req(String s){
        return "req";
    }
}

效果就是多出了我在注解上写得mydemo和mycontroller

2、@ApiOperation

这个是一个方法上注解，参数有value和notes两个，这个具体的看代码和显示效果

package org.example.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author weiguorong
 * @date 2021/2/13 19:33
 */
@RestController
@Api(tags = {"mydemo","mycontroller"})
public class MyController {

    @GetMapping("/get")
    @ApiOperation(value = "post方法，执行新的操作",notes = "备注post请求")
    public String get(String a,String b){
        return "get";
    }

    @PostMapping("/post")
    public String post(){
        return "post";
    }

    @RequestMapping("req")
    public String req(String s){
        return "req";
    }
}

看了我的只有get标注了这个注解，再看效果



这个就相当于一个备注，可以更清楚这个接口的信息

3、@ApiParam

该注解常用在方法的参数上，该注解的参数有name，value，和required

package org.example.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author weiguorong
 * @date 2021/2/13 19:33
 */
@RestController
@Api(tags = {"mydemo","mycontroller"})
public class MyController {

    @GetMapping("/get")
    @ApiOperation(value = "post方法，执行新的操作",notes = "备注post请求")
    public String get(
            @ApiParam(name = "用户名",value = "新增的用户名",required = true) String a,
            @ApiParam(name = "密码",value = "新增的密码",required = true) String b){
        return "get";
    }

    @PostMapping("/post")
    public String post(){
        return "post";
    }

    @RequestMapping("req")
    public String req(String s){
        return "req";
    }
}

从效果图中就可以看出name和value代表的方法的参数名和这个参数描述，这里说一下required，看见截图里的那个标红色星号，代表说明该参数是否必要，就更你填信息标红星号的是一个意思，你也可以这样理解

4、@ApiImplicitParam

这注解是在方法上的，要跟上面那个区分开，老规矩把代码和效果图插上，

    @GetMapping("/test")
    @ApiImplicitParam(name = "a",value = "传进来的参数a",required = true,paramType = "参数a",dataType = "键值对")
    public String test(int a,int b){
        return "test";
    }

5、@ApiImplicitParams

这个注解就跟上面跟那个有点关系了，其实这个就是上面那个的复合形式
还是代码和效果图插上

    @GetMapping("/test")
    //@ApiImplicitParam(name = "a",value = "传进来的参数a",required = true,paramType = "参数a",dataType = "键值对")
    @ApiImplicitParams(value =
            {@ApiImplicitParam(name = "a",value = "传进来的参数a",required = true,paramType = "参数a",dataType = "键值对"),
            @ApiImplicitParam(name = "b",value = "传进来的参数b",required = false,paramType = "参数b",dataType = "键值对")}
    )
    public String test(int a,int b){
        return "test";
    }

6、@ApiIgnore

这个注解是在方法上的，是忽略当前的方法，不生成api帮助文档，这个很容易理解的

7、@ApiModel和@ApiModelProperty

这两个注解一般用在实体类上，@ApiModel是如果这个实体类作为返回值类型的时候，该注解将会解析，@ApiModelProperty则是注解在字段上，
先创个实体类

package org.example.pojo;

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

import java.util.Objects;

/**
 * @author weiguorong
 * @date 2021/2/14 1:26
 */
@ApiModel(value = "自定义实体类User",description = "存储User的数据")
public class User {
    @ApiModelProperty(name = "主键(id)",value = "主键",required = true,example = "1",hidden = false)
    private int id;
    @ApiModelProperty(name = "名字(id)",value = "名字",required = true,example = "张三",hidden = false)
    private String name;
    @ApiModelProperty(name = "密码(id)",value = "密码",required = true,example = "123456",hidden = false)
    private String password;

    public User() {
    }

    public User(int id, String name, String password) {
        this.id = id;
        this.name = name;
        this.password = password;
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        User user = (User) o;
        return id == user.id && Objects.equals(name, user.name) && Objects.equals(password, user.password);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, name, password);
    }

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

再写一个方法测试它

    @GetMapping("/testUser")
    public String testUser(){
        return "testUser";
    }

你会发现Models下面多出了一个自定义的实体类

该类的内容与上面的注解的注释都能对应上