Swagger array of objects
These types exist in most programming languages, though they may go by different names. Using these types, you can describe any data structures. Note that there is no null type; instead, the nullable attribute is used as a modifier of the base type.
Additional type -specific keywords can be used to refine the data type, for example, limit the string length or specify an enum of possible values. Did not find what you were looking for? Ask the community Found a mistake? Let us know.
Sign up here: SwaggerHub Swagger Inspector. Have an account? Sign in here: SwaggerHub Swagger Inspector. Data Types The data type of a schema is defined by the type keyword, for example, type: string. OpenAPI defines the following basic types: string this includes dates and files number integer boolean array object These types exist in most programming languages, though they may go by different names.
Mixed Types type takes a single value. Numbers OpenAPI has two numeric types, number and integerwhere number includes both integer and floating-point numbers. An optional format keyword serves as a hint for the tools to use a specific numeric type: type format Description number — Any numbers. Note that strings containing numbers, such as "17", are considered strings and not numbers. Strings A string of text is defined as: type: string String length can be restricted using minLength and maxLength : type: string minLength: 3 maxLength: 20 Note that an empty string "" is a valid string unless minLength or pattern is specified.
String Formats An optional format modifier serves as a hint at the contents and format of the string. Tools that do not support a specific format may default back to the type alone, as if the format is not specified.
Only the values that match this template will be accepted. Regular expressions are case-sensitive, that is, [a-z] and [A-Z] are different expressions. For example, pattern: pet matches petpetstore and carpet.REST API concepts and examples
Boolean type: boolean represents two values: true and false. Note that truthy and falsy values such as "true", "", 0 or null are not considered boolean values. Null OpenAPI 3. Note that null is different from an empty string "".
Correct type: integer nullable: true Incorrect type: null Incorrect as well type: - integer - null The example above may be mapped to the nullable types int? Integer in Java. In objects, a nullable property is not the same as an optional property, but some tools may choose to map an optional property to the null value.GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community. Already on GitHub?
Subscribe to RSS
Sign in to your account. The usage of the examples keyword is not valid. Here's how the fixed example looks in Swagger UI 3. Since your spec was generated by Swashbuckle, open an issue with them to address incorrect generation of response examples. Ok, let's ignore examples - the same problem happens if I use a string or null there. What about the result schema issue? Can you post a screenshot? Your spec looks OK in the latest UI version 3.
Something less than 3. I'll ask about updating on Swashbuckle repo! All good for me on an updated version in preview on Swashbuckle. New versions of Swagger UI look great! Skip to content. Dismiss Join GitHub today GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign up. New issue. Jump to bottom. Labels locked-by: lock-bot. Copy link Quote reply.
Q A Bug or feature request? Don't know - version detection link in issue template broken Which Swagger-UI version? How can I tell? How did you install Swagger-UI? Via Swashbuckle.Response Object. MediaType Object. Components Object. Did not find what you were looking for? Ask the community Found a mistake? Let us know. Sign up here: SwaggerHub Swagger Inspector.
Have an account? Sign in here: SwaggerHub Swagger Inspector. Each operation must have at least one response defined, usually a successful response. JSON is the most common format for data exchange, but not the only one possible. To specify the response media types, use the content keyword at the operation level. An operation typically returns one successful status code and one or more error statuses.
If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. Each response status requires a description. For example, you can describe the conditions for error responses. Markdown CommonMark can be used for rich text representation. User ID must be an integer and larger than 0.
Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. Response Body The schema keyword is used to describe the response body. A schema can define: an object or an array — typically used with JSON and XML APIs, a primitive data type such as a number or string — used for plain text responses, a file — see below.
The dark mode beta is finally here. Change your preferences any time. Stack Overflow for Teams is a private, secure spot for you and your coworkers to find and share information.
Imagine you are posting Order with multiple order items. Based on your XML document it seems that you won't need the type itemsArray. You could try to simplify the definition of newOrder by referencing the item type in items directly. Here are the relevant parts of the modified type definition. An additional note: as token is outside of the order element in your XML document you probably need to split your newOrder type into two and move token to the outer element. To give you an idea here's an example with all properties except token moved to the nested element order.
Learn more. Asked 3 years, 7 months ago. Active 3 years, 6 months ago. Viewed 9k times. Active Oldest Votes. Sign up or log in Sign up using Google. Sign up using Facebook. Sign up using Email and Password.
Post as a guest Name. Email Required, but never shown. The Overflow Blog. The Overflow How many jobs can be done at home? Featured on Meta. Community and Moderator guidelines for escalating issues via new response…. Feedback on Q2 Community Roadmap. Technical site integration observational experiment live on Stack Overflow.
Triage needs to be fixed urgently, and users need to be notified upon…. Dark Mode Beta - help us root out low-contrast and un-converted bits.
Related Hot Network Questions. Question feed.GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together. Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
Already on GitHub? Sign in to your account. Issue I can create an unstructured object to allow users to add a json object to the API. I do this using 'additionalProperties: true' and it appears to work fine. I get a drop down menu and select object and can edit the json. So that is working fine. But when I try and create an array of these objects I run into problems.
I can select the object from the drop down but cannot see any option to edit the json object. It is always empty.
Is it possible to have an array of simple, user defined, json objects in swagger? The proper way to represent what you want would be:. Thanks for the response. No, your right, for some reason it does not seem to support that type of input.
I assumed it would work via. I tried different combinations, even for the basic object, of the above format and it didnt work. I found it strange since it is a fairly basic structure to support. Do you know why the editor would not be able to support the way you described?
Is it a version issue? Does this mean that swagger does not support sending a user defined json object as part of the request body? Below is a picture of the issue. I can select any type other than object in the array and it works, sting, intYou can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer.
Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests. You can specify examples for objects, individual properties and operation parameters. To specify an example, you use the example or examples keys.
See below for details. Note: Do not confuse example values with default values. An example illustrates what the value is supposed to be.
A default value is what the server uses if the client does not provide the value. As you can see, each example has a distinct key name.
Also, in the code above, we used an optional summary keys with description. Note: the sample values you specify should match the parameter data type.
Note that in the code above, example is a child of schema. If schema refers to some object defined in the components section, then you should make example a child of the media type keyword:.
If needed, you can use multiple examples:. Note: The examples in response and request bodies are free-form, but are expected to be compatible with the body schema. You can also specify examples for objects and individual properties in the components section. Note that schemas and properties support single example but not multiple examples.
Note that arrays and array items support single example but not multiple examples. The URL should point to the resource that contains the literal example contents an object, file or image, for example :. Did not find what you were looking for? Ask the community Found a mistake? Let us know. Sign up here: SwaggerHub Swagger Inspector.
Have an account? Sign in here: SwaggerHub Swagger Inspector. Adding Examples You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Parameter Examples Here is an example of a parameter value: parameters: - in: query name: status schema: type: string enum: [approved, pending, closed, new] example: approved Example of a parameter value Multiple examples for a parameter: parameters: - in: query name: limit schema: type: integer maximum: 50 examples: Multiple examples zero: Distinct name value: 0 Example value summary: A sample limit value Optional description max: Distinct name value: 50 Example value summary: A sample limit value Optional description As you can see, each example has a distinct key name.
Object and Property Examples You can also specify examples for objects and individual properties in the components section. In property: components: schemas: User: Schema name type: object properties: id: type: integer format: int64 example: 1 Property example name: type: string example: New order Property example In object: components: schemas: User: Schema name type: object properties: id: type: integer name: type: string example: Object-level example id: 1 name: Jessica Smith Note that schemas and properties support single example but not multiple examples.
Array Example You can add an example of an individual array item: components: schemas: ArrayOfInt: type: array items: type: integer format: int64 example: 1 or an array-level example containing multiple items: components: schemas: ArrayOfInt: type: array items: type: integer format: int64 example: [1, 2, 3] If the array contains objects, you can specify a multi-item example as follows: components: schemas: ArrayOfUsers: type: array items: type: object properties: id: type: integer name: type: string example: - id: 10 name: Jessica Smith - id: 20 name: Ron Stewart Note that arrays and array items support single example but not multiple examples.
SwaggerHub Swagger Inspector.This document is licensed under The Apache License, Version 2. The OpenAPI Specification OAS defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
A document or set of documents that defines or describes an API. Media type definitions are spread across several resources. The major. Tooling which supports OAS 3. Such an update MUST only require changing the openapi property to the new minor version. For example, a valid OpenAPI 3. OAS 2. All field names in the specification are case sensitive.
This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. Primitives have an optional modifier property: format.
OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string -valued property, and can have any value. Formats such as "email""uuid"and so on, MAY be used even though undefined by this specification. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified. Throughout the specification description fields are noted as supporting CommonMark markdown formatting.