swagger注释API详细说明和示例

具体说明：

API详细说明

注释汇总

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

例子： 例子包括单个字段参数 和对象参数

package com.chehejia.vl.api;

import com.alibaba.fastjson.JSON;
import com.chehejia.boot.starter.cache.CacheManager;
import com.chehejia.framework.beans.model.Response;
import com.chehejia.starter.ois.model.response.ResponseModel;
import com.chehejia.starter.ois.service.OisClient;
import com.chehejia.starter.ois.utils.OisUtil;
import com.chehejia.vl.domain.VlTransitionPlan;
import com.chehejia.vl.domain.VlTransitionPlanItem;
import com.chehejia.vl.enums.BillType;
import com.chehejia.vl.enums.VLCacheKey;
import com.chehejia.vl.model.AppLogInfo;
import com.chehejia.vl.model.StatusCode;
import com.chehejia.vl.model.transitionPlan.*;
import com.chehejia.vl.service.TransitionPlanMiniService;
import com.chehejia.vl.utils.EmptyUtil;
import com.chehejia.vl.utils.FastJsonUtils;
import com.chehejia.vl.utils.SequenceUtil;
import com.google.common.collect.Lists;
import io.swagger.annotations.*;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.Assert;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.multipart.support.StandardMultipartHttpServletRequest;

import javax.servlet.http.HttpServletRequest;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.time.OffsetDateTime;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;


@Slf4j
@RestController
@RequestMapping("/plan")
public class TransitionPlanApi {

    @Autowired
    OisClient oisClient;

    @Autowired
    private TransitionPlanMiniService planService;

    @Autowired
    private CacheManager cacheManager;

    //调用接口
    final boolean useService = true;

    //swagger默认初始化参数,必须定义成常量
    class Contants{
      private Contants(){};
        public static final String planCode = "E10320180525154714001";
        public static final String vin1 = "10000000000001999";
        public static final String vin2 = "10000000000001998";
        public static final String valCode = "1234";
    }


    @ApiOperation("接口描述：[运输端]校验计划对应的操作码是否正确")
    @ApiResponses({
            @ApiResponse(code = 0, message = "校验成功"),
            @ApiResponse(code = 20001, message = "校验失败"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planCode", value = "计划编码", required = true, defaultValue = Contants.planCode),
            @ApiImplicitParam(name = "valCode", value = "验证码", required = true, defaultValue = Contants.valCode),
    })
    @RequestMapping(value = "/validate/{planCode}/{valCode}", method = RequestMethod.POST)
    public Response<Boolean> valiOperate(@PathVariable String planCode, @ApiParam("验证码") @PathVariable String valCode) {
       
    }

    @ApiOperation("接口描述：扫描车辆定位计划与车辆验车")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"), @ApiResponse(code = 20001, message = "查询不到数据"),
            @ApiResponse(code = 40001, message = "参数不合法"), @ApiResponse(code = 50001, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "vin", value = "VIN", required = true, defaultValue = Contants.vin1),
    })
    @RequestMapping(value = "/scanPlan/{vin}", method = RequestMethod.POST)
    public Response<VV3> scanPlan(@PathVariable String vin) {
       
    }

    @ApiOperation("接口描述：扫描车辆进行验车")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"),
            @ApiResponse(code = 20001, message = "查询不到数据"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planCode", value = "计划编码", required = true, defaultValue = Contants.planCode),
            @ApiImplicitParam(name = "vin", value = "VIN", required = true, defaultValue = Contants.vin1),
    })
    @RequestMapping(value = "/scan/{planCode}/{vin}", method = RequestMethod.POST)
    public Response<VV3> valiVin(@PathVariable String planCode, @PathVariable String vin) {
     
    }

    @ApiOperation("接口描述：单独上传质损图片")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planCode", value = "计划编码", required = true, defaultValue = Contants.planCode),
            @ApiImplicitParam(name = "vin", value = "VIN", required = true, defaultValue = Contants.vin1),
    })
    @RequestMapping(value = "/upload-damage/{planCode}/{vin}", method = RequestMethod.POST)
    public Response<String> uploadDamageImg(@PathVariable String planCode, @PathVariable String vin, HttpServletRequest request) {
       
    }

    @ApiOperation("接口描述：确认质损（下一步）")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"),
            @ApiResponse(code = 20001, message = "执行失败"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planCode", value = "计划编号", required = true, defaultValue = Contants.planCode),
            @ApiImplicitParam(name = "vin", value = "vin", required = true, defaultValue = Contants.vin1),
            @ApiImplicitParam(name = "eleQuity", value = "电量", defaultValue = "100"),
            @ApiImplicitParam(name = "mileage", value = "公里数", defaultValue = "50"),
            @ApiImplicitParam(name = "otherDesc", value = "其他备注", defaultValue = "测试备注信息"),
            @ApiImplicitParam(name = "damageInfo.veryBad", value = "是否严重事故", defaultValue = "true"),
            @ApiImplicitParam(name = "damageInfo.badPoint1", value = "质损部位1", defaultValue = "MLT2/MLB3"),
            @ApiImplicitParam(name = "damageInfo.badPoint2", value = "质损部位3", defaultValue = "MLT2/MLB3"),
            @ApiImplicitParam(name = "damageInfo.badPoint3", value = "质损部位3", defaultValue = "MLT2/MLB3"),
            @ApiImplicitParam(name = "damageInfo.imgs", value = "图片id集合", defaultValue = "imageCode1,imageCode2,imageCode3"),
            @ApiImplicitParam(name = "damageInfo.damageDesc", value = "质损描述", defaultValue = "质损测试数据描述"),
    })
    @RequestMapping(value = "/confirm-damage", method = RequestMethod.POST)
    public Response<Boolean> confirmDamageImg( DamageInfoAndDes damageInfoAndDes) {
       
    }

    @ApiOperation("接口描述：查询计划列表")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planType", value = "计划类型(10提车20交车)", required = true, defaultValue = "10"),
            @ApiImplicitParam(name = "date", value = "日期(格式：yyyy-MM-dd)"),
            @ApiImplicitParam(name = "dwCode", value = "道位编码"),
            @ApiImplicitParam(name = "carNo", value = "车牌号"),
    })
    @RequestMapping(value = "/query", method = RequestMethod.POST)
    public Response<List<TransionPlanInfo>> queryPlan(TransionPlanQuery query) {
   }

    @ApiOperation("接口描述：查看计划详情")
    @ApiResponses({
            @ApiResponse(code = 0, message = "执行成功"),
            @ApiResponse(code = 40001, message = "参数不合法"),
            @ApiResponse(code = 50001, message = "系统异常"),})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "planCode", value = "计划编码", required = true, defaultValue = Contants.planCode),
    })
    @RequestMapping(value = "/detail/{planCode}", method = RequestMethod.GET)
    public Response<TransionPlanInfoAndVin> lookPlanDetail(@PathVariable String planCode) {

      
    }

    
}