跳到主要内容

注释规范说明

注释规范​

Javadoc（Java）​

KDoc（Kotlin）​

ScalaDoc（Scala）​

Java 注释 Demo​


/**
 * 分类名称
 * 分类备注/描述
 *
 * @module 归属项目
 */
@RestController
@RequestMapping(value = "/pathOfCtrl")
public class MockCtrl {

    /**
    * api名称
    * api描述
    * @param param1 参数1的名称或描述
    * @param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link some.enum.or.constant.class}
    * @param param3 当目标枚举字段与当前字段名不一致,额外指定{@link some.enum.or.constant.class#property1}
    * @return 响应描述
    */
    @RequestMapping(value = "/pathOfApi1")
    public Result methodName1(long param1,
                      @RequestParam String param2,
                      @RequestParam(required = false, defaultValue = "defaultValueOfParam3") String param3){
        ...
    }


    /**
    * 默认使用`application/x-www-form-urlencoded`,
    * 对于`@RequestBody`将使用`application/json`
    * 可以用注解`@Deprecated`来表示api废弃
    * 也可以用注释`@deprecated`
    *
    * @deprecated 改用{@link #methodName3(String)}
    */
    @Deprecated
    @RequestMapping(value = "/pathOfApi2")
    public Result methodName2(@RequestBody MockDtoOrVo jsonModel){
        ...
    }

    /**
    * 所有注释或者参数描述中都可以使用`@link`来引用另一个API
    * 例如:
    * 请先访问{@link #methodName4(String)}

    * 也可以使用`@see`来引用另一个API
    *
    * @param param1 参数1的名称或描述 可以从{@link #methodName5(String)}中获得
    * @see #methodName6(String)
    * @deprecated 改用{@link #methodName7(String)}
    */
    @Deprecated
    @RequestMapping(value = "/pathOfApi3")
    public Result methodName3(long param1){
        ...
    }

    ...
}

Model(DTO/VO) Demo​

public class MockDtoOrVo {

    /**
     * 字段注释
     */
    private Long field1;

    private Double field2;//注释也可以写在这

    /**
     * 使用@see来说明当前字段的取值是某个枚举
     * @see some.enum.or.constant.class
     */
    private int field3;

    /**
     * 当目标枚举字段与当前字段名不一致,额外指定
     * @see some.enum.or.constant.class#property1
     */
    private int field4;

    /**
     * 可以用注解`@Deprecated`来表示字段被废弃
     * 也可以用注释`@deprecated`
     * @deprecated It's a secret
     */
    @Deprecated
    private int field5;

    /**
     * 如果使用javax.validation的话
     * 可以使用@NotBlank/@NotNull表示字段必须
     */
    @NotBlank
    @NotNull
    private String field6;

    ...
}

导出效果​

  • 列表页
接口名称接口路径接口分类状态tag
Mock String/mock/stringMock Apis已完成swagger
test
  • 详情页
基本信息
接口名称： Mock String                创   建   人：  admin
状    态：  已完成                   更新时间：  2019-12-07 22:31:28
Tag ：    swagger, test
接口路径： GET /mock/string
Mock 地址： http://127.0.0.1:3000/mock/172/mock/string

api.tags.delimiter​

在1.1.24版本之前使用api.tag.delimiter，如需使用最新配置，请更新插件

  • 用于分割 tags, 默认 tags 的分隔符是,\n
    • 如规则得到的tags是a,b,则会被切割为[a,b]
    • 如希望a,b视为一个规则,可以设置api.tags.delimiter=\n,则不再对,进行切割
    • 如希望将a|b|c切割为[a,b,c],可以设置api.tags.delimiter=|\n
    • 如希望将a,b|c,d切割为[a,b,c,d],可以设置apis.tags.delimiter=|,\n