07-2-接口文档管理工具-swagger注解使用__ev

swagger参考demo?

package com.example.swagger2.controller;


import com.example.swagger2.exception.SwaggerException;
import com.example.swagger2.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@Api(tags = "接口服务", value = "/api/v1/swagger/**")
@RestController
@RequestMapping("/api/v1/swagger")
public class ApiController {

    @ApiOperation("保存用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名字", required = true, paramType = "path"),
            @ApiImplicitParam(name = "age", dataType = "int", value = "年龄", required = true, paramType = "query")
    })
    @PostMapping("/{name}")
    @ResponseBody
    public Boolean save(
            @PathVariable("name") String name,
            @RequestParam("age") Integer age
    ) {
        userInfo.put(name, new User(name, age));
        return true;
    }


    @ApiOperation("查询年龄")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名字", required = true, paramType = "path")
    })
    @ApiResponses({
            @ApiResponse(code = 404, message = "用户不存在", response = SwaggerException.class)
    })
    @GetMapping("/{name}")
    @ResponseBody
    public User get(
            @PathVariable("name") String name
    ) throws SwaggerException {
        if (!userInfo.containsKey(name)) {
            throw new SwaggerException(name + "不存在！");
        }
        return userInfo.get(name);
    }

    public static Map<String, User> userInfo = new HashMap<>(16);
}

package com.example.swagger2.model;

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

@Data
@AllArgsConstructor
@ApiModel(description = "用户信息")
public class User {

    @ApiModelProperty(value = "姓名")
    String name;
    @ApiModelProperty(value = "年龄")
    Integer age;
}

• swagger相关注解介绍

  注解	位置	说明
  @Api	类	加载Controller类上,表示对类的说明
  @ApiModel	类(通常是实体类)	描述实体类的作用，通常表示接口接收参数的实体对象
  @ApiModelProperty	属性	描述实体类的属性，（用对象接收参数时，描述对象的一个字段）
  @ApiOperation	方法	说明方法的用途、作用
  @ApiImplicitParams	方法	表示一组参数说明
  @ApiImplicitParam	方法	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面的属性
  @ApiParam	方法入参或者方法之上	单个参数的描述信息，描述form表单、url参数

  @ApiImplicitParam注解详解：

  属性	取值	作用
  paramType		查询参数类型
  	path	以地址的形式（rest风格）提交数据
  	query	直接跟参数完成自动映射赋值(/add/user?name=zhangsan)
  	body	以流的形式提交 仅支持POST
  	header	参数在request headers 里边提交
  	form	以form表单的形式提交 仅支持POST
  dataType		参数的数据类型 只作为标志说明，并没有实际验证
  	Long
  	String
  name		接收参数名(方法入参的名称)
  value		接收参数的意义描述（描述信息）
  required		参数是否必填
  	true	必填
  	false	非必填
  defaultValue		默认值

其它注解：

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

把注解应用到项目中

package com.itheima.stock.controller;

import com.itheima.stock.pojo.entity.SysUser;
import com.itheima.stock.service.UserService;
import com.itheima.stock.vo.req.LoginReqVo;
import com.itheima.stock.vo.resp.LoginRespVo;
import com.itheima.stock.vo.resp.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Map;
@Api(tags = "用户相关接口处理器")
@RestController
@RequestMapping("/api")
public class UserController {
    @Autowired
    private UserService userService;
@ApiOperation(value = "根据用户名查询用户信息")
@ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "path")
    @GetMapping("/user/{username}")
    public SysUser findUserInfoByUsername(@PathVariable("username") String username) {
        return userService.findUserInfoByUsername(username);
    }
@ApiOperation(value = "用户登录")
    @PostMapping("/login")
    public R<R<LoginRespVo>> login(@RequestBody LoginReqVo loginReqVo) {
        return R.ok(userService.login(loginReqVo));
    }
    @ApiOperation(value = "获取验证码")
    @GetMapping("/captcha")
    public R<Map> getCaptchaCode() {
        return userService.getCaptchaCode();
    }
}

?查看效果