Openapi enum default value. All values in an enum must adhere to the specified type.

Openapi enum default value In the parameter section, the enum is just defined as string with no information about what valid values are Feb 10, 2023 · This is a quick post to show how to configure an ASP. Feb 13, 2023 · I have defined a Transport enum as below, i want the Open API Specification to show the enum values as string instead of numeric. additionalProperties – the value can be a boolean (true or false) or an OpenAPI schema. In TypeSpec, you can specify the path for a namespace, interface, or operation using the @route decorator. However, in some Apr 5, 2023 · Avoid breaking API code when using enums in API design. SIMPLIFY_ONEOF_ANYOF_ENUM: when set to true, oneOf/anyOf with only enum sub-schemas all containing enum values will be converted to a single enum This is enabled by default The default values for contentType are as follows, where an n/a in the contentEncoding column means that the presence or value of contentEncoding is irrelevant: type title description example (examples in OpenAPI 3. The value type must be the same as the parameter’s data type. NET API that has Swagger UI (with Swashbuckle), they are shown as numbers by default. Aug 3, 2022 · openapi openapi-generator-maven-plugin openapi. [JsonConverter(typeof(JsonStringEnumConverter))] public enum Busine The @Schema annotation, provided by the Swagger/OpenAPI specification, is used in Spring Boot applications to enhance API documentation. Mar 11, 2025 · I'm trying to get proper enum generation via OpenAPI in my ASP. When properly defined via OpenAPI, a consumer There are four kinds of values: objects, arrays, scalars, and null. Apr 17, 2025 · Not reproducable. 0 and 3. Models; using Swashbuckle. Enums Note OAS 2 This page applies to OpenAPI Specification ver. The type of the parameters, their format and their serialization can be specified using additional fields as shown in the next sections. Oct 20, 2021 · I am currently trying to have null values for Enum, as per the OpenAPI specs, this is possible. spring. yaml -g java -o enum-issue results in TestPostRequest. It’s important to note a constant parameter is not the same as the default parameter value. To recap the answer to May 26, 2018 · A query parameter containing a comma-separated list of values is defined as an array. This is the common base class of all Java language enumeration classes. I found this not very user friendly as you’d need insight in what the number represents. Instead of enum names, I need to set it to enum values. By default, if Jun 29, 2019 · I have a open api yaml file like below. When properly defined via OpenAPI, a consumer Overviewvalid-server-variable-default-value-for-enum Overview This rule belongs to the openapi-v3-standards-validation ruleset and states that: If a default value is provided for the server variable and an enumeration list is also defined using the enum property, the default value must exist in this list. Learn how to maintain seamless API integration, even when new enum values like currencies are introduced, ensuring your application's robustness and adaptability. How to specify a property as null or a reference? discusses how to specify a property as null or a reference using jsonschema. Jul 1, 2020 · My API has a enum field in request body. Corresponds to the {?param_name} URI template. properties – individual property definitions must follow OpenAPI schema rules and not standard JSON Schema. 2 (fka Swagger). To allow use of a different default $schema value for all Schema Objects contained within an OAS document, a jsonSchemaDialect value may be set within the OpenAPI Object. NET during JSON and XML serialization with Newtonsoft. Add a Enum Schema Filter using Microsoft. oas. When I generate swagger UI, its showing enum with allowed value as enum names. Example: enum: - name: a x-field-uid: 1 description: some description - name: b x-field OpenAPI 3. If appropriate, name the member 'None' (or one of the additional permitted names). Enums are particularly useful when you want to constrain a field to a limited set of predefined values. 2 options: exclude "enum" from the list of keywords that follow JSON Schema spec and to re-define "enum" to allow null value with "nullable" even if null is not explicitly listed in "enum". x supports the enum (enumerated list) keyword for all schemaObject object properties, including parameters, request bodies, and responses. When a null is received, it can be translated in the correct part of the code into the default, and this default doesn't have to be known in the rest of the code (that just passes along a null). 0 - Default value of a field of type Enum Asked 4 years, 3 months ago Modified 2 years, 1 month ago Viewed 17k times May 7, 2025 · The OpenAPI Specification (OAS) version 3. 1 provides robust mechanisms for defining APIs, including the ability to specify enumerated types (enums). The enum converters convert incoming strings to their enum by comparing with the OpenAPI enum values. Converters. 1) enum format properties items required Nesting adds complexity to definitions. I am willing to contribute a patch myself for this. Feb 5, 2021 · Describe the bug Specifying a default value for an enum parameter on a REST API has no effect on the generated openapi. 0 The parameter May 1, 2024 · The processor will now use our custom Enum at all places in the generated source code where AnEnum is used in the OpenAPI description, and we can use our more descriptive enum value names. OpenApi. net asked Aug 3, 2022 at 19:18 user1318369 735 5 17 35 Jan 26, 2022 · 5 I have an Enum declared on a API like this : public enum Currencies { RON = 1, USD, EUR, GBP, CHF, PLN, CAD, HUF, NOK, SEK } but when I use NSwag to generate a HttpClient, it starts from 0 and I obtain this: public enum Currencies { [System. The enum values must be of the same type as the parameter Oct 10, 2019 · To do this just decorate the field in the model as follows, which will tell the JsonSerializer to convert between the string and int values of the enum : public class Person{public int Id { get Apr 21, 2019 · OpenAPI spec should be clarified here, but we would need to figure out how best to do it. I'll poke around to see if there's any guidance at the schema level about the best way to model bitwise enums. 0 with openapi-generator 4. Otherwise, assign zero to the most frequently used member. The code shown below has been taken from this article and is purely to inform anyone else who has this question or has been facing a similar problem: Decorate the desired properties in a model: Sep 20, 2023 · I tried on my own and I find this solution to your problem. Additionally, values can result from referencing enum members and union variants. I am trying to follow the steps as given here https://swagger. Sep 26, 2023 · Explore solutions to handle unknown enum values in . NET Core API to serialize all enum properties to strings in HTTP responses. , enums) in web API models, you probably aren't getting the behavior you are expecting, both for required and for optional properties. All values in an enum must adhere to the specified type. SwaggerGen; namespace Your Aug 4, 2021 · What is the OpenAPI Specification? The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. v3. The generated Java code correctly contains the enum and it's used for the field, but the initialization of the field is incorrectly done with a string, that of course does not compile. For example, if a field has an array value, the JSON array representation will be used: { "field": [ 1, 2, 3 ] } All field names in the specification are case sensitive. By default, an array may have any number of items, which matches your "none or more" requirement. You might also want to use the discriminator (an OpenAPI concept). Parameter doesn't have defaultValue attribute which is required in our case because we have default value available for one of our query parameters an Feb 2, 2025 · Microsoft. Dec 20, 2022 · From the OpenAPI Swagger documentation, query parameters support the following style values: form (default): ampersand-separated values, also known as form-style query expansion. Sep 30, 2016 · I have a RESTful Web API project, and I have 2 different Enum scenarios that I'm unsure of re best practice. The following code demonstrates this: Jan 5, 2018 · type: - 'null' - string but the Swagger Editor shows an error: Schema "type" key must be a string What is the correct way to define a nullable property in OpenAPI? Feb 14, 2025 · I'd like to make the default enum value name configurable, but leave the existing default so that users who like the current default can continue using it without any breakage. 0 Apr 6, 2023 · We have a field based on an enum and specifying a default value. This is not intended use of default and can lead to unexpected behavior in some Swagger tools. For example, if type is string, then default can be "foo" but cannot be 1. 0 specification about schemas The Schema Object allows the definition of input and output data types. 0 definition so that they will be displayed in the Model tab of Swagger UI? Example here has an enum option for the status proper Apr 25, 2025 · Enums and Constants Relevant source files This document explains how the openapi-python-client generator handles enumeration types and constant values when parsing OpenAPI specifications and generating typed Python client code. jar generate -g jaxrs-spec -o out -i enum. Feb 14, 2020 · I created an enum on my server with integer values set manually rather than the default increment up from 0 public enum UserType { Anonymous = 0, Customer = 10, Technician = 21, Man Oct 3, 2024 · Ideally it should also inject x-ms-enum if you want on enums and give key/values since it's so widely supported by OpenAPI client generators. 1. I'm looking to do the same thing with swagger. Dec 11, 2019 · Learn how to use enum values in Swagger/OpenAPI annotations V3 for Java applications on Stack Overflow. I've tried with java -jar openapi-generator-cli-7. 0 document, semantically equivalent to the original OpenAPI 3. swagger. EnumMember(Value = @"RON")] RON = 0, [System. For that I used @Sch How do I define default value for property in swagger generated from following API? public class SearchQuery { public string OrderBy { get; set; } [DefaultValue(OrderDirection. If the values are predefined, then it's an array of enum. 0? 0 Peter Over a year ago Apr 17, 2025 · Description WIth openapi-generator version 7. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. OpenAPI lets you define dictionaries where the keys are strings. The enum keyword restricts the value of a JSON property to a fixed set of values. The default value is false. com` port: LANGUAGE PRIMITIVES Boolean Double Float Integer Long Object String boolean byte [] RESERVED WORDS _ abstract apiclient apiexception apiresponse assert boolean break byte case catch char class configuration const continue default do double else enum extends file final finally float for goto if implements import instanceof int interface list localdate localreturntype localtime localvaraccept Feb 4, 2025 · The default value of an uninitialized enumeration, just like other value types, is zero. 0, SHALL be a valid OpenAPI 3. options. Xml. This: The default values for contentType are as follows, where an n/a in the contentEncoding column means that the presence or value of contentEncoding is irrelevant: Open Api Parameter Class In this article Definition Constructors Fields Properties Show 3 more Definition Namespace: Microsoft. 2 Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. These types can be objects, but also primitives and arrays. But why? And how? In OpenAPI, the paths object [v2, v3] is the top-level structure for defining the operations of the API, organized by the “path” for the operation. Is it possible to define an object as a value for an enum in swagger open API 3. net not to throw up when my enum doesn't match string value provided in the json property? This happens when I create enum based on current documentation, but the third party AP Aug 12, 2022 · Yeah, I was also considering a separate enum, but thought that there might be a solution. OpenApi v1. No - Let me clarify, as of now enum supports just a single value. Models Assembly: Microsoft. Serialization. AspNetCore. This is used to define names of the enum items. OpenAPI 2. A non-flags-attributed enumeration should define a member that has the value of zero so that the default value is a valid value of the enumeration. OpenApi does not generate a schema for an enum that is a key in a dictionary #60163 Jul 8, 2023 · How to make enum serialization default to string in minimal API endpoints and Swagger? Asked 2 years, 4 months ago Modified 2 years, 4 months ago Viewed 13k times It creates Java enum classes and a Spring ConverterFactory with the name {package-name}. java with line 54 being: Aug 13, 2025 · What are Enumerations with names and values? Enumerations with names and values are a way to define a set of named constants in OpenAPI, providing both context and specific value to developers, which helps prevent ambiguities and improves consistency in data types exchanged. 0. Overview The generator supports both enum types and constant For example, a valid OpenAPI 3. Text. Jun 12, 2025 · A flags enum with a [JsonConverterAttribute] is defined as type: string in the generated schema with no enum property, since the value could be any combination of the enum values. Json, and System. Follow our best practices for designing enum APIs with fixed sets of values & dynamic enums. 0 spec default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. type as a list is not valid in OpenAPI (even though it is valid in JSON Schema): Oct 27, 2022 · 1 I am using OpenApi 3. Sep 20, 2024 · For this particular case, I'm inclined to say that we wouldn't modify the default behavior in the implementation to support actually emitting the enum values given the constraints of the schema. These names will be displayed alongside the enum values in the format value = varname: Oct 29, 2025 · As a simple example of this customization, you might choose to always inline enum schemas. I want to assign empty string value as default to string type property. 2 document. This will end in a compile error for our code generation. Parameter schemas don’t support custom validation functions, complex data structures METADATA CONFIG OPTIONS These options may be applied as additional-properties (cli) or configOptions (plugins). To define a dictionary, use type: object and use the additionalProperties keyword to specify the type of values in key/value pairs. This has the added benefit of catching all unlisted enum values, not just the one you explicitly declared. 2. After some googling, I found this solution: 1. Admin would be returned from the API as Dec 27, 2024 · If you use non-nullable value types (e. This is done by setting CreateSchemaReferenceId to a delegate that returns null for enum types, and otherwise returns the value from the default implementation. How have Enum definitions evolved in OpenAPI 3. dll Package: Microsoft. This is used for comments in the code (like javadoc if the target language is java). Desc # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server. By default enum properties are returned as a number, for example if you have the following enum for user roles: public enum Role { Admin, User } A user with the Role = Role. g. Apr 23, 2025 · Although OpenAPI provides a lot of flexibility for defining and using variables, it’s not close to providing everything you could ever want: Server variables can only be strings and have limited validation options. Note OAS 3 This guide is for OpenAPI 3. Description How can I generate an OpenAPI schema with reusable enum classes? If I have 2 pydantic models that reference the same enum class. How can I get Json. Mixed Types type takes a single value. JsonSerializerOptions. Open Api. Although, x-ms-enum may be popular, it's still a non-standard extension onto the spec which is why we don't generate it by default. The serialized representation used for . 1? The default value is the one that the server uses if the client does not supply the parameter value in the request. Currently type enum is always defaulted to INVALID_VALUE_OPENAPI_GENERATED, despite the field default bein Jan 3, 2020 · Thanks for the reply. When an API can return two or more different types of objects (aka polymorphism), use oneOf or anyOf to describe those schemas (a JSON Schema concept). 0 and I have encountered a requirement with enum with some extra fields. Is there a way to define a default value for an array with a value? I want to be able to pass an array of enums, but if it wasn't passed I'd like to give it a default array with one of the enum values. Sep 17, 2023 · The enum property specifies possible values, and in this example, only one value can be used. Runtime. spaceDelimited: space-separated array values. When the value of the @route decorator contains path parameters, operations within the scope of the decorator must declare parameters The item schema must be an OpenAPI schema and not a standard JSON Schema. Scenario 1 : Straightforward Enum Param My API method requires a parameter called rule Sep 8, 2022 · When using enums in a . NET Core 9 project so I can create a typescript schema using User) {} With isArray set to true, the enum can be selected as a multi-select: Enums schema By default, the enum property will add a raw definition of Enum on the parameter. What is the OpenAPI Specification? The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. 0 there was a new feature to set a default value for enum values. AddJsonOptions(options => { // Add JSON converter for enum strings and configure naming policy. 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. This enhances documentation and improves API consumer experience by providing clear expectations. Then just add the reference in the path (do not insert the enum inside the {}) and Sep 20, 2024 · I have an operation with that takes in an enum as query string parameter, and returns it back in the response. Any; using Microsoft. First of all I defined the enum under the component/schemas section like: component: schemas: status: type: string enum: [scheduled, active] default: active Just insert the default attribute to set that value as the default one for your request. Aug 24, 2017 · OpenAPI v3. annotations. Enumeration classes are all serializable and receive special handling by the serialization mechanism. Which also used to work. 6. json --additional-properties=library=quarkus,enumPropertyNaming=legacy Please provide as requested by bug reports: Prefer CLI steps, including the language, libraries and various options. These values can be created with object values, array values, scalar values and initializers, and the null literal respectively. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility. By default, the generated OpenAPI schema will look something like this: Mar 7, 2019 · To define default values for parameters for Swagger UI in . For example, a string-to-string dictionary like this: Sep 16, 2020 · Describe the bug io. To learn about the latest version, visit OpenAPI 3 pages. EnumMember Aug 2, 2022 · I am using OpenApi 3. If you need to specify descriptions for enum items, you can do this in the description of the parameter or property: Jul 26, 2021 · Open API Spec V2. - breed: type: 'string' enum: - Persian - Tabby - Siamese The above specification works fine for most cases. 12. The OAS defines an enum according to the JSON Schema Specification. 9 of The Java Language Specification. For example, the sort parameter in: Nov 5, 2025 · By default, enums defined in OpenAPI are considered closed during code generation. Feb 11, 2011 · One consideration for the use case where a default enum is desired is to use a nullable variable. Oct 3, 2017 · Whenever a default is set on an enum parameter it becomes impossible to send another version than the default. This object is an extended subset of Aliases: x-enumDescriptions x-enum-varnames You can provide variable names for enum values with x-enum-varnames. Parameters don’t support dynamic default values, computed values, or conditional values. If needed, you can restrict the number of items using minItems and maxItems, and optionally enforce uniqueItems: true. default – the default value must conform to the specified schema. I find it better to always use nullable value types. require that "enum" explicitly lists null to allow it. Each item is a string, one of available, pending or sold, and the default if not supplied is "available" If you define enum types with non default value such as declaring 0 value with UNKNOWN and want to omit the default value from generated swagger file, use omit_enum_default_value. Apr 4, 2025 · Is there an existing issue for this? I have searched the existing issues Describe the bug A formdata endpoint with an enum parameter that has a default value causes OpenAPI document generation to t Oct 28, 2025 · Bug Report Checklist Have you provided a full/minimal spec to reproduce the issue? Have you validated the input using an OpenAPI validator? Have you tested with the latest master to confirm the iss Mar 18, 2019 · As long as the defined values do not equal default(int), or the default of whatever you chose your enum type to be, you can still work with the enum as expected, and catch unitialized values with a switch default case. You can use the enum keyword to specify possible values of a request parameter or a model property. Documentation for the openapi Generator METADATA CONFIG OPTIONS These options may be applied as additional-properties (cli) or configOptions (plugins). Excerpt from the OpenAPI 3. Refer to configuration docs for more details. Concerning omitting the default value, how is it omitted based on the answer? I would would like to omit it from the spec, as it is redundant - Programmatically the stated default value is null in my code. It covers the implementation of both simple and complex enum use cases, as well as constant value handling. The value must be an array with at least one element and each Feb 14, 2023 · Generation Details openapi-generator-cli generate -i default-for-referenced-enum. Json, System. This means that introducing a new member to an enum can become a breaking change for consumers of older versions of the SDK. Demonstration API definition Feb 19, 2022 · Learn how to document enum in Swagger using the Maven plugin and verify the generated JSON document in the Swagger editor. a number field with default value 1 an object field, containing itself a number field with default value 2 If a client sends an empty payload, we should agree that field1 value is supposed to be 1, but what about field2 value? field2 is not specified, so it must be considered as null field2 should be an object build with default values Jul 17, 2023 · Is have a open api yaml: ParentPlanState: type: string enum: - NOT_PLANNABLE - PLANNABLE - REQUEST_EXTRA_DAY - REQUEST_EXTRA_DAY_DURING_HOLIDAY Is used in other object like: Mar 18, 2022 · Does anyone know how to define possible enum values in an OpenAPI 2. More information about enums, including descriptions of the implicitly declared methods synthesized by the compiler, can be found in section 8. 2 document, upon changing its openapi property to 3. Jul 9, 2018 · While the default value could be implied from this, from a programmatic perspective what should be expected as the value for "status" (and for other parameters in a similar case)? The value is of type array, it doesn't have a default. Add(new JsonStringEnumConverter()); }); The API turns out to accept an integer as you can see in the OpenAPI file generated (with the new system that use MapOpenApi()) : Enum extensions x-enum-varnames can be used to have another enum name for the corresponding value. io/docs 4. My preferred solution would be to make the existing value settable, and provide a new config option to set it. NET Core, the following article defines a custom schema filter for your DefaultValue attribute in your Model class. Some elements of the specification support the example or examples keyword for this purpose. Oct 1, 2024 · Describe the bug By default using an enum in class will result in a generic schema type of just number (not even an OpenApi enum of integers) Example enum Dec 13, 2021 · Description I'm trying to provide a default value for a generated class that uses an enum. x-enum-descriptions can be used to provide an individual description for each value. Utilizing the allowableValues property effectively allows you to specify a list of acceptable values for your enum parameters, ensuring that users have clear expectations about the options available when they interact with your API. Enum Parameters The enum keyword allows you to restrict a parameter value to a fixed set of values. Mar 20, 2022 · Enumerated values can be great building blocks, but they introduce risks for an API (Pixabay) Using enums as parameters for APIs Enums work by creating a type-safe mnemonic within your code Apr 21, 2020 · I already searched in Google "How to X in FastAPI" and didn't find any information. StringToEnumConverterFactory that does create enum converters for all generated enums. It creates Java enum classes and a Spring ConverterFactory with the name {package-name}. yaml or a pre-selection of the respective value in the swagger-ui. A dictionary (also known as a map, hashmap or associative array) is a set of key/value pairs. LANGUAGE PRIMITIVES Boolean Double Float Integer Long Object String boolean byte [] RESERVED WORDS _ abstract apiclient apiexception apiresponse assert boolean break byte case catch char class configuration const continue default do double else enum extends file final finally float for goto if implements import instanceof int interface list localdate localreturntype localtime localvaraccept Feb 27, 2025 · Learn how to use enums as request parameters in Spring REST controllers and how to handle exceptions triggered by invalid input. Sometimes, this is desirable because particular enums can be rigidly defined and not changing in the foreseeable future (country codes might be a good example of this). What is the way to do this Test: type: object required: ['', ''] properties: tes Dec 8, 2024 · }) . Polymorphism adds more complexity. qiwepva taunfa ivfy ywgxp tisfc dqzmx qrbjb kgk kerzn fxr abav lnem degbvv una rjbj