search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.74k stars 1.29k forks source link

Client generation:no support for schema references "$ref" in open api json files #1880

Closed danilsonStan closed 4 years ago

danilsonStan commented 5 years ago

It would be really nice if client generation from a open api file (json) supported schema references. Examples: "$ref": "#/components/schemas/GeneralError" "$ref": "/PersonDefinition.json#/paths/%2Fv2.3%2Fpersons"

If you split your endpoint definition in multiple files, but still have a main.json that references the other schema definitions via "$ref" it is not possible generate just one client.

danilsonStan commented 5 years ago

I jast analyzed the code a bit. In NSwag.Core, there is an enum "SwaggerOperationMethod".

It more or less reflects the values that are described as values for the Path Item object (see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject ) but there is no $ref value.

RicoSuter commented 5 years ago

Yes, this is missing ATM

RicoSuter commented 5 years ago

Can you provide a complete sample of this $ref usage?

RicoSuter commented 5 years ago

Added PR https://github.com/RSuter/NSwag/pull/1953

knoepdan commented 5 years ago

Sorry for the late reply (and cant find my credentials for danilsonStan). I would just like to give you 2 use cases that we would like to use in our company.

1. summary help In one project, we have many many controllers and endpoints. Initially, we had one huge help file (open api file), that the customers have become used to. However, it has become unmaintanable (unfortunately, we cannot use nswag or swashbuckle to generate the json help for reasons i dont want to go into here), so we split the huge json file into multiple files. However, we would like to keep the overview file. Therefore, we would like to have one entry file, from where we reference the endpoint definitions in other json files.

2. endpoints that reference the same dto objects Some of your endpoints points use the same input/output objects. In fact, in C# its the exact same object. (this is pretty commen for Odata expand objects). Now instead of having them defined twice, we would love to externalize these objects, into a separate file so they can just be referenced via $ref .

So basically, the support for $ref would enable us to split the open api definition files into multiple files in the way we want them and still be able to generate clients.

RicoSuter commented 5 years ago

With my pr you could $ref into a path object of another openapi file but i think it wouldnt work if the file is just the path item json. Would that be ok? (I think this is even intended in this way)

danilsonStan commented 5 years ago

Thanks for your reply. yes i think it would work. (and generally, we should be so flexible to adapt your structure to the tools)

luk355 commented 4 years ago

thanks @RicoSuter for looking into this. I've created PR with requested unit tests:

https://github.com/RicoSuter/NSwag/pull/3086