Swagger常用的几个注解

其他 2020-02-07 17:06:01 阅读次数: 0

实习期间，做一些练手项目，前后端分离以后测试成了问题，刚好接触到这一款工具，完美的解决了前后端分离以后后端开发测试，刚好最近经常使用，于是整理了一些常见的注解。
Swagger几种常见注解的了解：
@Api：
作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。
参数：
1.description：描述这个类的作用。
2.tags：设置这个类的一个标签。
@ApiOperation：
用于发送一个请求，value可以加以说明
@ApiImplicitParam：
作用于参数：用于对参数进行操作
里面含有的属性包括以下几种：

  1. name ：参数名。（注意这个名字要与实际方法中的参数名一致，不然会导致swagger界面出现多个参数）
  2. value ： 参数的具体意义，作用。
  3. required ： 参数是否必填。
  4. dataType ：参数的数据类型。
  5. paramType ：查询参数类型，这里有几种形式：
  6. 类型 作用
    path 以地址的形式提交数据
    query 直接跟参数完成自动映射赋值
    body 以流的形式提交 仅支持POST
    header 参数在request headers 里边提交
    form 以form表单的形式提交 仅支持POST

注意如果想要传入一个对象类型的参数，不使用@ApiImplicitParam,然后在方法参数加上注解@RequestBody这样就会使用json的形式发送参数
如果方法的参数中有一个对象，有一个普通参数，那么只需要对普通参数类型注解@ApiImplicitParam即可，而对象类型和上面处理方法一样

多个参数：@ApiImplicitParams
在注解里面在包含多个@ApiImplicitParam注解，每个注解使用逗号隔开
@ApiParam
增加对参数的元信息说明
下面通过一个简单项目中的代码展示几种常见的案例：（代码只是一部分，不能执行，只是参考书写格式即可）

package com.gwdl.csxt.control.modules.hire.resume.controller;

/**
 * @Auther: yxc
 * @Date: 2019/12/16
 * @Description:招聘模块控制类
 */

import com.gwdl.csxt.control.common.base.constant.DataResult;
import com.gwdl.csxt.control.common.utils.DateUtils;
import com.gwdl.csxt.control.modules.hire.resume.controller.vo.ResumeVO;
import com.gwdl.csxt.control.modules.hire.resume.entity.EvaluationClass;
import com.gwdl.csxt.control.modules.hire.resume.entity.Resume;
import com.gwdl.csxt.control.modules.hire.resume.service.ResumeService;
import com.gwdl.csxt.control.modules.hire.resume.utils.StringToDate;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.util.ResourceUtils;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.*;
import java.util.Date;
import java.util.List;
import java.util.UUID;

@Api(tags = "招聘管理",description = "用于招聘模块的测试")
@Controller(value = "/resume")
public class ResumeController {
    @Autowired
    private ResumeService resumeService;

    /**
     * 功能描述: 根据id查询简历信息
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ApiOperation(value = "简历的查询")
    @ApiImplicitParam(value = "根据简历id查询唯一的一份简历", name = "resumeID", paramType = "query", dataType = "String")
    @RequestMapping(value="findResumeByID",method = RequestMethod.GET)
    @ResponseBody
    public DataResult findResume(String resumeID){
        //调用业务层代码查询
        Resume resume = resumeService.findResumeByID(resumeID);
        DataResult result=new DataResult();
        if(resume!=null){
            result.setStatus(0);
            result.setMsg("查询成功");
            result.setData(resume);
            return result;
        }else{
            result.setMsg("无查询用户");
            result.setStatus(1);
            return result;
        }
    }

    /**
     * 功能描述: 查询所有简历
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ApiOperation(value = "查询所有简历")
    @ApiImplicitParam(value = "查询参数",required = false)
    @RequestMapping(value="findAllResume",method = RequestMethod.GET)
    @ResponseBody
    public DataResult findAllResume(){
        DataResult result=new DataResult();
        List<Resume> allResume = resumeService.findAllResume();
        if(allResume!=null){
            result.setStatus(0);
            result.setMsg("查询成功");
            result.setData(allResume);
            return result;
        }else{
            result.setStatus(1);
            result.setMsg("查询数据失败");
            return result;
        }
    }

    /**
     * 功能描述: 根据id删除简历
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @RequestMapping(value="deleteResume",method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "删除简历")
    @ApiImplicitParam(value = "删除简历", name = "resumeID", paramType = "query", dataType = "String")
    public DataResult deleteResume(String resumeID){
        DataResult result=new DataResult();
        int delete = resumeService.deleteResume(resumeID);
        if(delete==1){
            result.setMsg("删除成功");
            result.setStatus(0);
            return result;
        }else{
            result.setMsg("删除失败");
            result.setStatus(1);
            return result;
        }
    }

    /**
     * 功能描述: 批量删除
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/20
     */
    @ApiOperation(value = "批量删除简历")
    @ApiImplicitParam(value = "批量删除",name="resumeID",dataType = "String",paramType = "query",allowMultiple =true )
    @ResponseBody
    @RequestMapping(value = "deleteMany",method = RequestMethod.GET)
    public DataResult deleteMany(String[] resumeID){
        DataResult result=new DataResult();
        resumeService.deleteMany(resumeID);
        result.setStatus(0);
        result.setMsg("删除成功");
        return result;
    }
    /**
     * 功能描述: 多条件查询简历
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ResponseBody
    @RequestMapping(value="findResumeByCand",method = RequestMethod.POST)
    @ApiOperation(value = "多条件查询")
    @ApiImplicitParams({
            @ApiImplicitParam(value="姓名",name="name",dataType="Stirng",paramType = "query"),
            @ApiImplicitParam(value="简历状态",name="status",dataType="Stirng",paramType = "query"),
            @ApiImplicitParam(value="简历来源",name="source",dataType="Stirng",paramType = "query"),
            @ApiImplicitParam(value="开始时间",name="startTime",dataType="Stirng",paramType = "query"),
            @ApiImplicitParam(value="结束时间",name="endTime",dataType="Stirng",paramType = "query")
    })
    public DataResult findResumeByCand(String name,String status,String source,String startTime,String endTime){
        DataResult result=new DataResult();
        List<Resume> resumeByCand = resumeService.findResumeByCand(name,status,source, startTime, endTime);
        if(resumeByCand!=null){
            result.setMsg("成功");
            result.setStatus(0);
            result.setData(resumeByCand);
            return result;
        }else{
            result.setMsg("失败");
            result.setStatus(1);
            return result;
        }
    }
    /**
     * 功能描述:新增简历
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ApiOperation(value = "新增简历")
    @ResponseBody
    @RequestMapping(value="insertResume",method = RequestMethod.POST)
    public DataResult insertResume(ResumeVO resumevo, HttpServletRequest request){
        //设置主键
        String s = UUID.randomUUID().toString();
        String replace = s.replace("-", "");
        resumevo.setResumeID(replace);
        //将时间格式转为可以插入数据库的格式
        String birthday = request.getParameter("birthday");
        Date date = StringToDate.StringFormatDate(birthday);
        resumevo.setBirthday(date);
        DataResult result=new DataResult();
        int i = resumeService.insertResume(resumevo);
        if(i==1){
            result.setMsg("新增成功");
            result.setStatus(0);
            return result;
        }else{
            result.setStatus(1);
            result.setMsg("新增失败");
            return result;
        }
    }


    /**
     * 功能描述: 更新简历
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ApiOperation(value = "更新简历")
    @ApiImplicitParam(value = "更新参数", name = "resumeID", paramType = "query",dataType = "String")
    @RequestMapping(value="updateResume",method = RequestMethod.POST)
    @ResponseBody
    public DataResult updateResume(@RequestBody ResumeVO resumevo, String resumeID){
        //前端获取到的时间数据需要进行类型转换
        DataResult dataResult=new DataResult();
        Date birthday = resumevo.getBirthday();
        String format = DateUtils.format(birthday, DateUtils.DATE_PATTERN);
        Date date = DateUtils.stringToDate(format, DateUtils.DATE_PATTERN);
        resumevo.setBirthday(date);
        int i = resumeService.updateResume(resumevo,resumeID);
        if(i==1){
            dataResult.setMsg("更新成功");
            dataResult.setStatus(1);
            dataResult.setData(resumevo);
            return dataResult;
        }else{
            dataResult.setMsg("更新失败");
            dataResult.setStatus(0);
            return dataResult;
        }
    }
    /**
     * 功能描述:更新简历回显数据
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/16
     */
    @ApiOperation(value = "更新简历回显数据")
    @ApiImplicitParam(value = "更新简历id", name = "resumeID", paramType = "query",dataType = "String")
    @RequestMapping(value="updateResumeUI",method = RequestMethod.GET)
    @ResponseBody
    public DataResult updateResumeUI(String resumeID){
        DataResult result = findResume(resumeID);
        return result;
    }


    /**
     * 功能描述:查看审核结果  评价
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/20
     */
    @RequestMapping(value="findRemark",method=RequestMethod.GET)
    @ResponseBody
    @ApiOperation("查看简历评价")
    @ApiImplicitParam(value = "简历评价",name="resumeID",paramType = "query",dataType = "String")
    public DataResult findRemark(String resumeID){
        Resume resume = resumeService.findResumeByID(resumeID);
        //简历
        EvaluationClass eva=new EvaluationClass();
        eva.setResumeID(resumeID);
        eva.setResumeNum(resume.getResumeNum());
        eva.setDescription(resume.getDescription());
        eva.setName(resume.getName());
        eva.setEvaluation(resume.getEvaluation());
        eva.setAuditorId(resume.getAuditorId());
        DataResult result=new DataResult();
        result.setData(eva);
        result.setMsg("成功");
        result.setStatus(1);
        return result;
    }
    /**
     * 功能描述: 文件上传功能 上传功能实现以后将文件的文件名保存到数据库中
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/19
     */
    @ApiOperation(value="文件上传")
    @ApiImplicitParam(value = "简历唯一ID",name="resumeID",dataType = "String",paramType = "query")
    @RequestMapping(value="uploadFile",consumes = "multipart/*",headers = "content-type=multipart/form-data",method = RequestMethod.POST)
    @ResponseBody
    public DataResult uploadFile(@ApiParam(value = "上传文件",required = true) MultipartFile file, String resumeID,HttpServletRequest request)throws IOException{
        DataResult result=new DataResult();
        if(file.isEmpty()){
            result.setMsg("文件不能为空");
            result.setStatus(1);
            return result;
        }
        //获取文件名
        String fileName=file.getOriginalFilename();
        //获取文件的后缀名 从后面往前截取
        String suffixName=fileName.substring(fileName.lastIndexOf("."));
        //输入流位置
        String uploadFilePath= ResourceUtils.getURL("classpath:").getPath()+"uploadFile/";
        System.out.println(uploadFilePath);
        //下载文件路径
        File dest=new File(uploadFilePath+fileName);
        //如果目录不存在就新建一个
        if(!dest.getParentFile().exists()){
            dest.getParentFile().mkdirs();
        }
        file.transferTo(dest);
        //如果上传成功的话就将文件名保存到数据库中去
        int i = resumeService.updateResumeAttachmentAddress(fileName, resumeID);
        if(i==1){
            result.setMsg("上传成功");
            result.setStatus(1);
            return result;
        }else{
            result.setMsg("文件上传成功，但文件路径没有进入数据库");
            result.setStatus(1);
            return result;
        }

    }

    /**
     * 功能描述: 文件的下载功能,首先获取到数据库中的附件名称，然后实现下载功能
     * @auther: yxc
     * @return: null
     * @date: 2019/12/19
     */
    @ApiOperation(value="文件下载")
    @ApiImplicitParam(value="简历ID",name="resumeID",paramType = "query",dataType = "String")
    @RequestMapping(value="/downFile",method = RequestMethod.GET)
    @ResponseBody
    public DataResult downFile(String resumeID,HttpServletRequest request, HttpServletResponse response)throws Exception{
        DataResult result=new DataResult();
        Resume resume = resumeService.findResumeByID(resumeID);
        String fileName=resume.getResumeAttachmentAddress();
        System.out.println(fileName);
        if(fileName!=null){
            String realPath=ResourceUtils.getURL("classpath:").getPath()+"uploadFile/";
            File file=new File(realPath,fileName);
            if(file.exists()){
                response.setContentType("application/force-download");//设置下载不打开
                //设置文件的中文名称乱码问题
                fileName=new String(fileName.getBytes("UTF-8"),"ISO-8859-1");
                response.addHeader("Content-Disposition",
                        "addachment;fileName="+fileName);//设置文件名
                byte[] buffer=new byte[1024];
                FileInputStream input=null;
                BufferedInputStream bufferInput=null;
                input=new FileInputStream(file);
                bufferInput=new BufferedInputStream(input);
                OutputStream out=response.getOutputStream();
                int i=input.read(buffer);
                while(i!=-1){
                    out.write(buffer,0,i);
                    i=input.read(buffer);
                }
                System.out.println("success");
                //关闭资源
                if(bufferInput!=null){
                    bufferInput.close();
                }
                if(input!=null){
                    input.close();
                }
                if(out!=null){
                    out.close();
                }
            }
        }
        result.setMsg("下载成功");
       return result;
    }

    /**
     * 功能描述: 文件在线浏览功能
     * @auther: yxc
     * @return: DataResult
     * @date: 2019/12/20
     */
    @RequestMapping(value="/openFile",method = RequestMethod.POST)
    @ApiOperation(value="在线浏览")
    @ApiImplicitParam(value="文件浏览",name="resumeID",dataType = "String",paramType = "query")
    public void openFile(String resumeID,HttpServletRequest request) throws Exception {
        //首先查询到简历
        Resume resume = resumeService.findResumeByID(resumeID);
        //获取附件的名称
        String fileName=resume.getResumeAttachmentAddress();
        String uploadFilePath= ResourceUtils.getURL("classpath:").getPath()+"uploadFile/";
        System.out.println(uploadFilePath+fileName);
        //调用程序打开文件
        String cmd="rundll32 url.dll FileProtocolHandler file://"+uploadFilePath+fileName;
        Runtime runtime=Runtime.getRuntime();
        runtime.exec(cmd);

    }

}

上面实现了一些常见方法的swagger测试，如传进的参数多个怎么处理，是一个对象怎么处理，是集合数组怎么处理，是文件怎么处理。写的不是很完善，还有很多其他的功能没有使用起来。但最常见的使用基本包含，需要扩展的可以查看更多的资料。

木木夕&从心开始
发布了33 篇原创文章 · 获赞 37 · 访问量 4383
私信 关注

猜你喜欢

转载自blog.csdn.net/weixin_42142899/article/details/103609810
今日推荐
美国拟限制 AI 大模型出口中国和俄罗斯
苹果将与 OpenAI 达成协议，将 ChatGPT 应用于 iPhone
openKylin 社区生态委员会第六次会议圆满召开
阿里云正式发布通义千问 2.5
Python 3.13 发布首个 Beta：实验性自由线程模式和 JIT、改进交互式解释器
Stack Overflow 拿我的代码去训练 AI 大模型，还封了我的账号
Pop!_OS 的 COSMIC 桌面完成 App Store 上架工作
报告：Django 仍然是 74% 开发者的首选
《2024 年一季度互联网投融资运行情况》研究报告
15 年前上了“FFmpeg 耻辱柱”，今天他还得谢谢咱——腾讯QQPlayer一雪前耻？
TIOBE 5 月榜单：Fortran “复活”进入 Top 10
GCC 14.1 发布
周排行
curl的POST请求，封装方法
8.1.1. Integer Types
Java基础 Day05(个人复习整理)
Python - Django - 中间件 process_exception
小L的试卷
【Shell编程】 （函数）判断用户是否存在
python(css样式)
spring ant path 匹配原则 - 【笔记】
《JavaScript与JScript从入门到精通》(美)James.Jaworski.中译本.扫描版.pdf
Eclipse运行带参数的java程序
每日归档
更多
2024-05-12(0)
2024-05-11(38)
2024-05-10(38)
2024-05-09(35)
2024-05-08(42)
2024-05-07(14)
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)
2024-05-03(19)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022