Array of string enums in query parameter

[dchenz]

I'm trying to generate an OpenAPI 3.1 spec for a query parameter that can take multiple values from a set of values.

is there a way to do this using struct tags?

The struct definition I tried / expected to work. It works for single enum, but not for arrays.

Color []string `query:"color" nullable:"false" explode:"false" enum="red,yellow,orange"`

Generated output.

{
  "name": "color",
  "in": "query",
  "schema": {
    "items": {
      "type": "string"
    },
    "type": "array"
  },
  "explode": false
}

Desired output.

{
  "name": "color",
  "in": "query",
  "schema": {
    "items": {
      "type": "string",
      "enum": ["red", "yellow", "orange"]
    },
    "type": "array"
  },
  "explode": false
}

Thanks!

[TophatRay]

+1

[vearutop]

Hello, enum= should be enum: in field tag, but that would still be something you don't want.
Field tags are applied to fields, you want enum for an item of a slice that's held by the field.

There is no attempt to apply filed tags to field sub elements, because that would be a misleading behavior due to large variety of possible kinds of sub elements with undefined expectations, e.g. [][]string, []int, map[string]map[int]bool, etc...

https://go.dev/play/p/bn12aLBhtiK

package main

import (
	"encoding/json"
	"net/http"

	"github.com/swaggest/openapi-go/openapi31"
)

func main() {
	r := openapi31.NewReflector()

	type req struct {
		Color []string `query:"color" nullable:"false" explode:"false" enum:"red,yellow,orange"`
	}

	oc, _ := r.NewOperationContext(http.MethodGet, "/")

	oc.AddReqStructure(req{})

	_ = r.AddOperation(oc)

	j, _ := json.MarshalIndent(r.SpecSchema(), "", " ")
	println(string(j))
}

{
 "openapi": "3.1.0",
 "info": {
  "title": "",
  "version": ""
 },
 "paths": {
  "/": {
   "get": {
    "parameters": [
     {
      "name": "color",
      "in": "query",
      "schema": {
       "enum": [
        "red",
        "yellow",
        "orange"
       ],
       "items": {
        "type": "string"
       },
       "type": "array"
      },
      "explode": false
     }
    ],
    "responses": {
     "204": {
      "description": "No Content"
     }
    }
   }
  }
 }
}

In this case, I think the cleanest solution is to declare a named type for color and implement Enumer on it.

https://go.dev/play/p/kV7EyXHdaUP

package main

import (
	"encoding/json"
	"net/http"

	"github.com/swaggest/openapi-go/openapi31"
)

type color string

func (color) Enum() []any {
	return []any{"red", "yellow", "orange"}
}

func main() {
	r := openapi31.NewReflector()

	type req struct {
		Color []color `query:"color" nullable:"false" explode:"false"`
	}

	oc, _ := r.NewOperationContext(http.MethodGet, "/")

	oc.AddReqStructure(req{})

	_ = r.AddOperation(oc)

	j, _ := json.MarshalIndent(r.SpecSchema(), "", " ")
	println(string(j))
}

{
 "openapi": "3.1.0",
 "info": {
  "title": "",
  "version": ""
 },
 "paths": {
  "/": {
   "get": {
    "parameters": [
     {
      "name": "color",
      "in": "query",
      "schema": {
       "items": {
        "$ref": "#/components/schemas/Color"
       },
       "type": "array"
      },
      "explode": false
     }
    ],
    "responses": {
     "204": {
      "description": "No Content"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Color": {
    "enum": [
     "red",
     "yellow",
     "orange"
    ],
    "type": "string"
   }
  }
 }
}

[dchenz]

Thanks for the quick response! Works perfectly