I’m trying to use NSwagStudio with servicestack, and I’m getting errors thrown, probably because SS is generating API v1.0 code and NSwagStudio expects 2.0.
Are there plans to update this? I really don’t want to have to convert my whole project to MVC or Core just to support automatic client generation via Swagger…
Thanks, I just found that.
Now the issue I’m seeing is that the NSwagStudio barfs when it detects
"parameters": [
{
"$ref": "#/parameters/Accept"
}
]
at the end of each API definition in the openapi returned data.
I don’t know if this is a SS openapi issue, or a NSwagStudio bug, but removing all those blocks allows the generator in the studio to work.
The path #/parameters/Accept is correct, and an Accept does exist there, but I’m not sure what it’s used for.
Is there any way to configure the OpenApi feature to omit it? I haven’t looked into this yet, but it’s clearly a difference between the SS generated definition and the .Net CORE 2 MVC one.
The use of $ref is prevalent in the Open API 2.0 Specification.
You can the OpenApiFeature Filters when registering the plugin to modify the Typed DTO before it’s serialized.
E.g. the ApiDeclarationFilter is called with the root OpenApiDeclaration which you can traverse to access any property.
The thing is that this is not in a DTO, it’s in the definition of the path.
I’ve attached an abridged example of the JSON, and what I don’t understand is who or what is appending the additional parameters block to each route. What is this used for? I have no Accept property or object defined in my solution.
Would I still be able to use the ApiDeclarationFilter to prevent this?
{
"swagger": "2.0",
"info": {
"title": "QuestEngage",
"version": "1.0"
},
"host": "localhost:65000",
"basePath": "/",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/api/currentUser": {
"get": {
"tags": [
"api"
],
"operationId": "GetCurrentUserDetailsRequestcurrentUser_Get",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/GetCurrentUserDetailsResponse"
}
}
},
"deprecated": false
},
"parameters": [
{
"$ref": "#/parameters/Accept"
}
]
},
"/api/snippet/": {
"put": {
"tags": [
"api"
],
"operationId": "SaveSnippetRequestsnippet_Create",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "Snippet",
"in": "query",
"type": "string"
},
{
"name": "body",
"in": "body",
"schema": {
"$ref": "#/definitions/SaveSnippetRequest"
}
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/SaveSnippetResponse"
}
}
},
"deprecated": false
},
"parameters": [
{
"$ref": "#/parameters/Accept"
}
]
},
:
:
:
},
"parameters": {
"Accept": {
"name": "Accept",
"in": "header",
"description": "Accept Header",
"type": "string",
"required": true,
"enum": [
"application/json"
]
}
},
"securityDefinitions": {
"basic": {
"type": "basic"
}
},
"tags": [
{
"name": "api"
}
]
}
You can modify the entire Open API JSON spec that’s returned by modifying the OpenApiDeclaration object graph using the ApiDeclarationFilter.
All the DTOs showing which C# property maps to which JSON property can be found in the Open API Specification DTOs.
OK, so the following removes the Accept type:
Plugins.Add(new OpenApiFeature()
{
ApiDeclarationFilter = (declaration =>
{
foreach(var pathkey in declaration.Paths.Keys)
for (var paramidx = 0; paramidx < declaration.Paths[pathkey].Parameters.Count; paramidx++)
{
var param = declaration.Paths[pathkey].Parameters[paramidx];
if (param.Ref.EndsWith("/Accept"))
declaration.Paths[pathkey].Parameters.RemoveAt(paramidx);
}
})
});
I’m still not clear why this Accept parameter has been added at all.
Should the inclusion of this be a configuration option on the OpenApiFeature?
ServiceStack uses same endpoint for returning json/xml/csv and returning type depends on Accept headers. By default Azure autorest generated clients does not generate required Accept headers even if specify in OpenAPI with
"produces": [
"application/json"
],
And these clients do not work at all. This is due they assume that xml and json services use different endpoint locations.
The bug is reported here. Unfortunately this bug is not being fixed in Autorest client and has not got ETA when Autorest team will resolve it. To workaround this issue we have to declare Accept header in OpenAPI specification explicity. Parameter headers should be supported by other Open API clients, because it’s part of the specification, if they are not supported this is the bug of the client implementation. Swagger 2.0 UI which we are using in OpenAPI supports Accept header parameter and works correctly with it.
When this bug will be resolved in Azure Autorest we’ll be able to remove Accept header from parameters and do not use it there.
That’s great, thanks.
I contacted the developer of NSwag too, and he’s fixed his NJsonSchema library to handle this reference type, so it was indeed a bug in the studio app.