Markdown is supported in the Swagger Editor. Below is an example of using Markdown in an OpenAPI (Swagger) document: swagger: ‘2.0’ info: version: 0.0.0 title: Markdown description: | # Heading Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`. Horizontal rule: — Bullet list: * apples * oranges * pears Numbered list: 1. apples 2. oranges 3. … Read more
Your example is correct. how do I document what the restrictions are for the “key” in the object? Ideally I’d like to say something like “it’s not just any arbitrary string, it’s the ID that corresponds to the child”. Is this supported in any way? OpenAPI 3.1 OAS 3.1 fully supports JSON Schema 2020-12, including … Read more
That’s because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these: /{foo} /{bar} are identical, even if foo must be a string, and bar … Read more
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
Maybe this can help: swagger: ‘2.0’ info: version: 1.0.0 title: Based on “Basic Auth Example” description: > An example for how to use Auth with Swagger. host: basic-auth-server.herokuapp.com schemes: – http – https securityDefinitions: Bearer: type: apiKey name: Authorization in: header paths: /: get: security: – Bearer: [] responses: ‘200’: description: ‘Will send `Authenticated`’ ‘403’: … Read more
Free-form query parameters can be described using OpenAPI 3.x, but not OpenAPI 2.0 (Swagger 2.0). The parameter must have type: object with the serialization method style: form and explode: true. The object will be serialized as ?prop1=value1&prop2=value2&…, where individual prop=value pairs are the object properties. openapi: 3.0.3 … paths: /users: get: parameters: – in: query … Read more