标签: #参数约束

写接口文档时，我把分页、排序、筛选参数声明复用了，结果每个接口都长得差不多，那差异化配置到底加在哪里

接口文档的复用困境源于混淆了参数声明与参数约束。解决之道在于将接口契约分为两层：结构层定义参数名称、类型等通用格式，实现复用；约束层则针对每个接口，明确具体的取值范围、白名单和业务规则，实现差异化。通过OpenAPI的`enum`、独立schema或文档中的专属约束表格，可清晰传达每个接口的独特限制，避免文档流于形式。