如何在 Swagger 模型中定义具有任意键的映射
How can I define a Map with arbitrary keys in a Swagger model
如何在 Swagger 模型中使用任意键定义 map
假设我有以下国际化模型(在 Ruby 风格的伪代码中,假设使用类似 Globalize
的东西)
class Thingy
translates :name
attribute :code
end
我的 API 希望能够 return 类似
{
"thingy": {
"code": "barn",
"translations": {
"default": "barn",
"en": "barn",
"ru": "cарай",
"fr": "grange",
"nl": "schuur"
}
}
}
但我不想在实际中限制翻译键的范围API
我可以在我的 swagger 文档中定义
definitions:
thingy:
required:
- code
properties:
code:
type: string
additionalProperties:
translations:
required:
- default
property:
default:
type: string
additonalProperties: string
那是有效的,但是 Swagger Codegen 不会在 additionalProperties
之外生成任何东西,而且与能够以某种方式定义 map
类型并混合使用必需键和任意键相比,它不是很明确.
任何从事国际化工作的人都会遇到类似的问题,所以我的问题是,其他人是如何处理这种情况的?
虽然上述定义在理论上是有效的,但它并没有转化为您要描述的内容,也没有得到 Swagger 的真正支持。
为了描述您想要的结构,您需要以下定义:
thingy:
type: object
required:
- code
properties:
code:
type: string
translations:
type: object
required:
- default
properties:
default:
type: string
additonalProperties:
type: string
虽然您 可以 定义内联内部对象,但我强烈建议您将定义外部化并使用 $ref
从 translations
定义.
至于代码生成器,最近引入了对地图的支持,所以它应该可以工作。如果您发现它没有,请直接在包含示例 Swagger 定义的项目上打开一个问题以帮助调试。
这在 swagger-codegen-2.1.1-M1 (Java/JavaJaxRS) 下工作...根据 Ron 的建议...
YAML ...
translation:
required:
- default
properties:
default:
type: string
additionalProperties:
type: string
thingy:
required:
- code
properties:
code:
type: string
translations:
$ref: '#/definitions/translation'
创建具有 'default' 属性的地图 ...
public class Translation extends HashMap<String, String> {
/**
*
*/
@Expose
private String _default = null;
/**
* @return _default the _default
*/
public String getDefault() {
return _default;
}
/**
* @param _default to set
*/
public void setDefault(String _default) {
this._default = _default;
}
}
它又嵌入到一个 Thingy 中.....
public class Thingy {
/**
*
*/
@Expose
private String code = null;
/**
*
*/
@Expose
private Translation translations = null;
/**
* @return code the code
*/
public String getCode() {
return code;
}
/**
* @param code to set
*/
public void setCode(String code) {
this.code = code;
}
/**
* @return translations the Translations
*/
public Translation getTranslations() {
return translations;
}
/**
* @param translations the Translations to set
*/
public void setTranslations(Translation translations) {
this.translations = translations;
}
}
如何在 Swagger 模型中使用任意键定义 map
假设我有以下国际化模型(在 Ruby 风格的伪代码中,假设使用类似 Globalize
的东西)
class Thingy
translates :name
attribute :code
end
我的 API 希望能够 return 类似
{
"thingy": {
"code": "barn",
"translations": {
"default": "barn",
"en": "barn",
"ru": "cарай",
"fr": "grange",
"nl": "schuur"
}
}
}
但我不想在实际中限制翻译键的范围API
我可以在我的 swagger 文档中定义
definitions:
thingy:
required:
- code
properties:
code:
type: string
additionalProperties:
translations:
required:
- default
property:
default:
type: string
additonalProperties: string
那是有效的,但是 Swagger Codegen 不会在 additionalProperties
之外生成任何东西,而且与能够以某种方式定义 map
类型并混合使用必需键和任意键相比,它不是很明确.
任何从事国际化工作的人都会遇到类似的问题,所以我的问题是,其他人是如何处理这种情况的?
虽然上述定义在理论上是有效的,但它并没有转化为您要描述的内容,也没有得到 Swagger 的真正支持。
为了描述您想要的结构,您需要以下定义:
thingy:
type: object
required:
- code
properties:
code:
type: string
translations:
type: object
required:
- default
properties:
default:
type: string
additonalProperties:
type: string
虽然您 可以 定义内联内部对象,但我强烈建议您将定义外部化并使用 $ref
从 translations
定义.
至于代码生成器,最近引入了对地图的支持,所以它应该可以工作。如果您发现它没有,请直接在包含示例 Swagger 定义的项目上打开一个问题以帮助调试。
这在 swagger-codegen-2.1.1-M1 (Java/JavaJaxRS) 下工作...根据 Ron 的建议...
YAML ...
translation:
required:
- default
properties:
default:
type: string
additionalProperties:
type: string
thingy:
required:
- code
properties:
code:
type: string
translations:
$ref: '#/definitions/translation'
创建具有 'default' 属性的地图 ...
public class Translation extends HashMap<String, String> {
/**
*
*/
@Expose
private String _default = null;
/**
* @return _default the _default
*/
public String getDefault() {
return _default;
}
/**
* @param _default to set
*/
public void setDefault(String _default) {
this._default = _default;
}
}
它又嵌入到一个 Thingy 中.....
public class Thingy {
/**
*
*/
@Expose
private String code = null;
/**
*
*/
@Expose
private Translation translations = null;
/**
* @return code the code
*/
public String getCode() {
return code;
}
/**
* @param code to set
*/
public void setCode(String code) {
this.code = code;
}
/**
* @return translations the Translations
*/
public Translation getTranslations() {
return translations;
}
/**
* @param translations the Translations to set
*/
public void setTranslations(Translation translations) {
this.translations = translations;
}
}