I'm working on an API which also generates swagger documentation. The issue is that for some reasons the request model/schema is not displayed in swagger UI but I don't get any error either.
I need to represent map to an array of strings . e.g. map[string][]string. Definition object definition is below.
{
"definitions": {
"versions": {
"type": "string",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
The support for maps is still not available in the UI - https://github.com/swagger-api/swagger-ui/issues/913.
You'd also want to change your definitions like this:
{
"definitions": {
"versions": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
To be clear, this defines a map where the values are arrays of strings.
Related
I'm using :
springdoc-openapi-ui : 1.6.6
springdoc-openapi-hateoas: 1.6.8
swagger-models: 2.1.12
spring-hateoas: 1.4.1
When i retrieve the generated openapi scheme from my rest services i get responses format for hateoas EntityModel withtout the content section. (v3/api-doc endpoint)
Is there a way to get the scheme generated with the content section ?
I get :
{
"EntityModelProject": {
"required": [
"name"
],
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"pattern": "[a-zA-Z0-9-_]*",
"type": "string"
},
"label": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Link"
}
}
}
}
}
I would like to have :
{
"EntityModelProject": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Link"
}
}
}
}
}
EDIT 1 :
After looking into spring-hateoas code i see that the EntitModel class contains the Jakson #JsonUnwrapped annotation on getContent method. In our project we use Gson and Nt jakson. With Gson serialization, the result containts de "content" section. Wtih jakson the content section is unwrap. I assume that, the scheme generated by springdoc-openapi interpret with jsackson and not gson.
EDIT 2 :
Indeed, the ModelResolver class of io.swagger.v3.core.jackson, read Jackson annotations to create schema. In my case, the #JsonUnwrapped annotation. Swagger schema generation seems to be not compatible with Gson formatted api.
I have a JSON file for OpenAPI 3 that contains the following:
"trait_hasProjectResponse_200": {
"description": "",
"content": {
"application/xml": {
"example": {
"value" : "<project><foo>1</foo><bar>2</bar></project>"
}
}
}
},
This results in the following display on the current swagger-ui:
How do I specify an example of XML for a parameter or response in the OpenAPI 3 spec? I have looked through the documentation and it seems to be targest mostly at JSON. What do I need to do the my output that is generating the OpenAPI 3 JSON file.
I have also tried to use the externalValue and have has similar difficulties.
Remove the value key from the example (value is only used with multiple examples).
"example": "<project><foo>1</foo><bar>2</bar></project>"
Alternatively, you can define a schema for the response, and Swagger UI will generate examples based on the schema. In your example, the schema is a project object that contains the foo array. You can specify [1, 2] as the example values for the foo array:
"components": {
"responses": {
"trait_hasProjectResponse_200": {
"description": "",
"content": {
"application/xml": {
"schema": {
"$ref": "#/components/schemas/project"
}
}
}
}
},
"schemas": {
"project": {
"type": "object",
"properties": {
"foo": {
"type": "array",
"items": {
"type": "integer"
},
"xml": {
"wrapped": false
},
"example": [1, 2]
}
}
}
}
}
This will give you:
I am creating an C# ASP.NET Core 2.0 REST API, all going well for the most part. It is using MVC routing to gen the REST API. The controllers are pretty simple.
// POST: api/Volume/{zoneID}/Set/{volume}
[HttpPost("{zoneId:int}/[action]/{volume:int}", Name = "Set")]
public IActionResult Set(int zoneId, int volume)
{
return CreateAndSend(strZonesLevel, zoneId, $"{volume:X2}");
}
Using the latest of everything, installed Swagger/Swashbuckle for AspNetCore 2.3.0 and the UI comes up with the APIs and all. The SwashBuckle UI works well, I can test the API etc.
The one exception is that on the UI, the Response type ALWAYS comes back as "Unknown Response Type."
https://i.stack.imgur.com/6qqBh.jpg
I have the following attributes in front of my class (all methods return the same type)
[Produces("application/json")]
[Route("api/Volume")]
[ProducesResponseType(typeof(ControllerResponseModel), 200)]
[ProducesResponseType(typeof(ControllerResponseModel), 400)]
[ProducesResponseType(typeof(ControllerResponseModel), 500)]
The generated JSON seems allright, the ControllerResponseModel is in the definition, and referenced in all the right places by the Volume API. Here is a subset.
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "AVController API"
},
"paths": {
"/api/Volume/{zoneId}/Set/{volume}": {
"post": {
"tags": ["Volume"],
"operationId": "ApiVolumeByZoneIdSetByVolumePost",
"consumes": [],
"produces": ["application/json"],
"parameters": [
{
"name": "zoneId",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "volume",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/ControllerResponseModel" }
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/ControllerResponseModel" }
}
},
"500": {
"description": "Server Error",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/ControllerResponseModel" }
}
}
}
}
}
},
"definitions": {
"ControllerResponseModel": {
"type": "object",
"properties": {
"command": { "type": "string" },
"message": { "type": "string" },
"url": { "type": "string" }
}
}
}
}
Any ideas why the UI would not be showing the return type and value? I have tried numerous things, like using gets instead of posts as well as using the [SwaggerResponse] attributes, but the results are the same.
This has been identified as an Edge browser issue with Swashbuckle, not the code posted here. It is reproducible on many sites. Issue has posted on GitHub # https://github.com/swagger-api/swagger-ui/issues/4337
We are using Swagger 2.0 for our documentation. We are Pro-grammatically creating swagger 2.0 spec straight out our data design documents.
Our Model is very complex and nested. I would like to understand can we define nested array objects defined inline.
for e.g :
{
"definitions": {
"user": {
"type": "object",
"required": ["name"],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["home",
"office"]
},
"line1": {
"type": "string"
}
},
"Person": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
}
}
}
We have many cases where we encounter this in our model and defining a #ref is not an option that we want to consider at this time. We need this to handled inline.
As per the following post : https://github.com/swagger-api/swagger-editor/issues/603#evenenter code heret-391465196 looks like its not supported to handle nested array objects defined inline.
Since lot of big enterprise's have a very complex data model we would like to have this this feature to be supported in swagger 2.0 spec.
Is there any thought on this feature to be added.
You document is just invalid and this is not about nested arrays: the property Person is not allowed in a Swagger 2.0 schema inside items.
The only allowed properties in a schema are: $ref, format, title, description, default, multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum, maxLength, minLength, pattern, maxItems, minItems, uniqueItems, maxProperties, minProperties, required, enum, additionalProperties, type, items, allOf, properties, discriminator, readOnly, xml, externalDocs, example.
I'm trying to use Swagger to describe web-api I'm building.
The problem is that I can't understand how to describe complex json object?
For example, how to describe this objects:
{
name: "Jhon",
address: [
{
type: "home",
line1: "1st street"
},
{
type: "office",
line1: "2nd street"
}
]
}
Okay, so based on the comments above, you want the following schema:
{
"definitions": {
"user": {
"type": "object",
"required": [ "name" ],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"$ref": "#/definitions/address"
}
}
}
},
"address": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [ "home", "office" ]
},
"line1": {
"type": "string"
}
}
}
}
}
I've made a few assumptions to make the sample a bit more complicated, to help in the future.
For the "user" object, I've declared that the "name" field is mandatory. If, for example, you also need the address to be mandatory, you can change the definition to "required": [ "name", "address" ].
We basically use a subset of json-schema to describe the models. Of course not everyone knows it, but it's fairly simple to learn and use.
For the address type you can see I also set the limit to two options - either home or office. You can add anything to that list, or remove the "enum" entirely to remove that constraint.
When the "type" of a property is "array", you need to accompany it with "items" which declares the internal type of the array. In this case, I referenced another definition, but that definition could have been inline as well. It's normally easier to maintain that way, especially if you need the "address" definition alone or within other models.
As requested, the inline version:
{
"definitions": {
"user": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"home",
"office"
]
},
"line1": {
"type": "string"
}
}
}
}
}
}
}
}