Прежде чем говорить с коллегами и некоторых технических документов интерфейса данного вопроса, и сослался на развязность, обратная связь, полученная от них:
«Много хлопот! Интерфейсы и документация код быть соединены друг с другом.»
«Описания полей написать несколько раз! Перемена изменить много мест!»
«Параметр запроса хочет четко описать написать кучу вещей !!»
Я также посмотрел под методами управления, чтобы быть так описания каждого параметра, сделать немного человечества ах!
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
А для возвращаемого значения, это чаще всего пример инкапсулирует объект ответа, подобный:
@Data
public class RespData{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private Object datas = "";
private Object meta = "";
public RespData(int status, Object datas) {
this.status = status;
if(status == Success){
this.datas = datas;
}else{
this.meta = datas;
}
}
public RespData(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
Результат, наконец, генерируется интерфейс документа, возвращаемое значение для данного описания:
Интерфейсный персонал при чтении документа, он должен выглядеть как это право
Я, наверное, говорить о том, как они использовали его: (не нужно делать, что много работы, иногда потому, что они не очень знакомы с тем, как другие люди будут видеть только то, как использовать)
Моя среда: SpringBoot Mybatis PLUS + 2,1 + 3.1.0 + Swagger2 Ломбок
Прежде всего, насколько это возможно в качестве ссылки, используемой для перевозки предметов, либо получить или пост метода, это хорошая привычка, вы можете также сделать некоторый пакет, я нахожусь здесь, чтобы инкапсулировать PageQuery объекты, есть pageNo, PAGESIZE два Integer (по сравнению с вами Все методы требуют параметры запроса поискового вызова эти две переменные, чтобы быть элегантной и некоторые из них?)
Тогда, так как он воплощен объект, вы не можете иметь большой кусок @ApiImplicitParams это! С этим комментарием: @ApiModelProperty.
@Data
public class ProductQuery extends PageQuery{
@ApiModelProperty(value = "商品类型ID")
private Long typeId;
}
Кроме того, чтобы преобразовать то, что данные возвращаются объекты, поддержка дженериков позволило
public class RespDataT<T>{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private T datas ;
private Object meta = "";
public RespDataT(T datas) {
this.datas = (T)datas;
this.status =Success;
}
public RespDataT(int status, T datas) {
this.status = status;
if(status == Success){
this.datas =(T) datas;
}else{
this.meta = datas;
}
}
public RespDataT(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
Ах, посмотрите на то, как написать контроллер
@ApiOperation("商品列表")
@GetMapping(path = "/list")
@ResponseBody
public RespDataT<IPage<Product>> list(ProductQuery query) {
try{
Page<Product> page = new Page<>(query.getPage(),query.getPageSize());
IPage<Product> datas = productMapper.getProductPage(page,query);
return new RespDataT<IPage<Product>>(datas);
}catch (Exception e) {
LOGGER.error(e.getMessage(),e);
return new RespDataT<IPage<Product>>(e);
}
}
Отличающееся тем, что Ipage Mybatis плюс параметры поискового вызова обеспечивается, Mybatis продукта плюс генерируется с помощью таблицы данных объекта.
Далее говорится, что, Mybatis плюс генератор кода, автоматически добавляется Swagger2 аннотаций! !
GlobalConfig gc = new GlobalConfig();
gc.setSwagger2(true);
Сгенерированный код:
Такие сгенерированные объекты были добавлены @ApiModelProperty, то есть: вы только что написали таблицы базы данных аннотаций, поля, объясните ваша документация API также хорошо.
Наконец, обратите внимание на внешний вид документа в результате, как чванство
раздел Запрос содержит параметры мы унаследовали параметры пейджинга, плюс новые атрибуты сущностей. (Объекты Page Я не добавлял @ApiModelProperty)
А затем вернуть данные документа:
Позже встречаются регулировки поля, mybatis плюс регенерат, что объект кода на нем.
(Во всяком случае, сгенерированный код, проекты в максимально возможной степени не изменить вручную, и простота в обслуживании)