Your usage of additionalProperties is correct and your model is correct. additionalProperties In Swagger/OpenAPI, hashmap keys are assumed to be strings, so the key type is not defined explicitly. additionalProperties define the type of hashmap values. So, this schema type: object additionalProperties: type: string defines a string-to-string map such as: { “en”: “English text”, “de”: … Read more
Swagger Editor Paste your OpenAPI 2.0 definition into https://editor.swagger.io and select Edit > Convert to OpenAPI 3 from the menu. Swagger Converter Converts OpenAPI 2.0 and Swagger 1.x definitions to OpenAPI 3.0. https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL This gives you JSON. If you want YAML, send the request with the Accept: application/yaml header: curl “https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL” -H “Accept: application/yaml” -o … Read more
This feature already exists in Swagger 2.0. The linked ticket talks about some specific mechanics of it which doesn’t affect the functionality of this feature. At the top level object (referred to as the Swagger Object), there’s a parameters property where you can define reusable parameters. You can give the parameter any name, and refer … Read more
Yes, you can have a path item that references another path item: paths: /ab: post: summary: … … responses: … /a-b: $ref: ‘#/paths/~1ab’ # <———— Here, ~1ab is an encoded version of /ab (see below). One limitation of this approach is that you cannot have operationId in all operations of the referenced path item. This … Read more
Mutually exclusive parameters are possible (sort of) in OpenAPI 3.x: Define the mutually exclusive parameters as object properties, and use oneOf or maxProperties to limit the object to just 1 property. Use the parameter serialization method style: form and explode: true, so that the object is serialized as ?propName=value. An example using the minProperties and … Read more
Using additionalPropertiesis the proper way to describe hashmap with OpenAPI (fka. Swagger) Specification but Swagger UI do not render them for now. The issue is tracked here https://github.com/swagger-api/swagger-ui/issues/1248 Meanwhile you can use this trick: define a non required property (defaultin the example below) of the same type of the map’s objects and give some hint … Read more
An arbitrary-type schema can be defined using an empty schema {}: # swagger: ‘2.0’ definitions: AnyValue: {} # openapi: 3.0.0 components: schemas: AnyValue: {} or if you want a description: # swagger: ‘2.0’ definitions: AnyValue: description: ‘Can be anything: string, number, array, object, etc. (except `null`)’ # openapi: 3.0.0 components: schemas: AnyValue: description: ‘Can be … Read more
TL;DR: $ref siblings are supported (to an extent) in OpenAPI 3.1. In previous OpenAPI versions, any keywords alongside $ref are ignored. OpenAPI 3.1 Your definition will work as expected when migrated to OpenAPI 3.1. This new version is fully compatible with JSON Schema 2020-12, which allows $ref siblings in schemas. openapi: 3.1.0 … components: schemas: … Read more
Yes it’s possible. In OpenAPI (fka. Swagger) 2.0 and 3.0, a hashmap is always a <string, something> map: The key is always a string and do not need to be defined. The value type is what you want and is defined with additionalProperties. Let’s say you want to describe a <string, string> hashmap like this … Read more
This depends on the OpenAPI version. OpenAPI 3.1 Your example is valid in OpenAPI 3.1, which is fully compatible with JSON Schema 2020-12. type: – ‘null’ # Note the quotes around ‘null’ – string # same as type: [‘null’, string] The above is equivalent to: oneOf: – type: ‘null’ # Note the quotes around ‘null’ … Read more