Comments (6)
Regarding model definition, there's no need for that. Even in JSON/JS there's a distinct difference between an object and a list. An object is represented by {} and a list by []. Models represent objects and not lists.
If you want to use a list of objects, that's simple. Have the type of the operation/parameter/property be "array" and the "items" have a "$ref" to the model definition. That effectively produces the result you're looking for.
Regarding the "json" type - if you declare that the operation's "consumes" field is "application/json", it basically tells the user that the model needs to be represented in a JSON format.
As for swagger-ui, if you've noticed a bug where the support for subtypes is lacking, please open an issue on https://github.com/wordnik/swagger-ui and it will get fixed.
Does this answer your requirements?
from openapi-specification.
Hey webron,
Thank you for the quick answer.
1.) We want to use model lists to define this case:
MyListClassA: {
items: {
"$ref": "MyListClassB"
}
}
MyListClassA: {
items: {
"type": "string"
}
}
We have nested arrays and we think this would be the cleanest solution to model this with swagger.
2.) We really like the "Try it!" button from swagger-ui, but it doesn't produce the correct output for our application though the "consumes" field is "application/json".
Our application requires JSON objects in the POST body and we still think the "json" paramType is necessary. How should the button react if the "consumes" field is "[application/json, text/html]"? With a "json" param type it would even be possible to have some query params and some others JSON encoded in the POST body.
3.) Sure the requirement to display the properties of parent models would need to go to swagger-ui. We were looking for someone from the community who is happy to earn some money with this, solve all three problems at once and push the results into the respective repositories.
Kind regards,
Ganesh
from openapi-specification.
- I don't understand the sample you're providing. You're defining the same model, each time with a different array in it. That's not a nested array or anything. If what you wanted to define was this:
MyListClassA: {
items: {
"$ref": "MyListClassB"
}
}
MyListClassB: {
items: {
"type": "string"
}
}
You can do that right now. However, keep in mind this is not a list of lists but rather a list of objects containing a list in them (basically, the difference between [[...], [...], [...]] and [{[...]}, {[...]}, {[...]}]).
Currently, nested arrays ([[...], [...], [...]]) are not supported by Swagger, though there's a ticket on it.
-
consumes/produces translates to HTTP headers which REST depends on. It affects the content of the request and response, which as far as I can tell affects the body but means nothing regarding the query/path parameters. If you offer two options for consumption as stated by your example, it means the user has to pick which one they'd want to use (swagger-ui should show a drop-down with the options) and the appropriate HTTP header will be sent to notify the server of the content type.
In my opinion, sending objects (which would require a structure such as JSON or XML) as a query parameter should be avoided in general for various reasons. That said, it doesn't mean it's not possible to do so, but there's currently no way to define in specifically. The "consumes" field affects the operation and follows the HTTP definitions. If you have a specific issue with swagger-ui not behaving as you expect it to, please open an issue about it on swagger-ui and it will be attended. -
Making a change as you request in number 1 is not trivial as it requires making changes to the spec itself. Obviously, you can always fork the swagger project and do as you please with them (the license we use is permissive), but it won't be easy to add this back into Swagger once the changes are done. Keep in mind this will also break third party tools that you may want to provide your clients with (client generators, ui's, automatic tests and so on).
Nevertheless, the right place to offer paid services about it would be in our mailing list. Another option is to contact @fehguy directly and discuss it with him.
from openapi-specification.
Hi webron,
The speed of your responses is amazing and I'm very pleased with it.
for 1) you are right with your guess. We had a typo in our example, which is very annoying considering the example's size. I don't understand why you say "you can do this right now". As far as I know a model currently cannot have "items", but only can have "properties". The idea of "items" is to have a class representing [...], thus an array with $ref to this class would be [[...], ..., [...]]. Wouldn't this be a great way to introduce nested arrays into swagger without nesting complex types?
for 2) I understand that the solution may be on swagger-ui side by providing a better interpretation of the consumes field (maybe in combination with paramType "body"?).
This said we will contact @fehguy for the two swagger-ui improvements. Have I been able to explain my idea of an "items" field in model object for nested array?
from openapi-specification.
-
You can have a model with a property of type array. Even if we introduced nested arrays, it would be by having an array of arrays. What you suggest is just another way of representing it and is not really required as an array of arrays would cover it (no point defining two methods of nested arrays). A model is an object. An object is not an array but can contain an array (thus the {...} representation). An array is a list of either primitives or objects and is not a model on its own (thus the [...] representation).
Again, nested arrays are simply not supported by the current specification, but you can follow on #40 to see if and when it is added. The idea you suggest is understood but it is not required (and we try to follow a structure similar to JSON schema's definition and your suggestion just doesn't follow it). -
Currently, the swagger-ui should have no issues dealing with "application/json" mime type for consumption. If you encounter an issue with it, please open it on swagger-ui directly.
from openapi-specification.
ok, thank you so much for your help. switching to swagger-ui ...
from openapi-specification.
Related Issues (20)
- Open Community (TDC) Meeting, Thursday 18 April 2024 HOT 5
- Format Registry documentation is not accurate / well published HOT 2
- Schema issues in documentation examples HOT 4
- Add tokenExchange grant type to list of allowed grant types for oauth2 shape
- Open Community (TDC) Meeting, Thursday 25 April 2024 HOT 7
- Define and document our schema publishing process HOT 1
- Schema development: main or branch, in parallel or at release time?
- Should we-organize our GitHub pages to a directory on main?
- Why does the JSON schema for 3.0 specify patternProperties for component names but allows additional properties?
- Support for `multipart/mixed` (and possibly better `multipart/*` support in general) HOT 5
- `description`/`summary` for Paths Object
- Support `multipart/byteranges` for 206 responses
- Support application/json-seq and similar JSON-based sequential formats HOT 1
- Did we break 3.2 compatibility by removing the Path Item $ref special case? HOT 12
- pipeDelimited and spaceDelimited style examples can be unresolvable HOT 10
- Encoding Object `contentType` field: "comma-separated list of the two types"? HOT 7
- Add appendix "Informative references" to published spec documents HOT 4
- Open Community (TDC) Meeting, Thursday 02 May 2024 HOT 3
- How are conflicts between `allowReserved` and RFC 3986 handled? HOT 6
- "body parameter" example in 3.x does not fit how Request Body Objects work HOT 6
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from openapi-specification.