How to add form field in query?

[kpoznyakov]

I would like to add something like custom fields with filters, if i made id myself, i made it like

      - description: long desc for all filters
        in: query
        name: filters
        schema:
          type: object
          description: another one desc
          example: {"filter1:foo:bar": "baz", "filter2:rick:mortн": 42}
          additionalProperties:
            type: string
        style: form
        explode: true  

how do i can done this with openapi-go?

[vearutop]

I'd suggest using JSON for object values in query parameters. It is supported by Swagger UI and automated request decoder in swaggest/rest.

Please check an example.
https://go.dev/play/p/hEjX7CnGrGs

package main

import (
	"fmt"
	"log"
	"net/http"

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

func main() {
	reflector := openapi3.Reflector{}

	type jsonFilter struct {
		Foo string `json:"foo"`
		Bar int    `json:"bar"`
	}

	type req struct {
		ID         string     `path:"id" example:"XXX-XXXXX"`
		Locale     string     `query:"locale" pattern:"^[a-z]{2}-[A-Z]{2}$"`
		JSONFilter jsonFilter `query:"json_filter"`
	}

	getOp := openapi3.Operation{}

	_ = reflector.SetRequest(&getOp, new(req), http.MethodGet)
	_ = reflector.Spec.AddOperation(http.MethodGet, "/things/{id}", getOp)

	schema, err := reflector.Spec.MarshalYAML()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(schema))
}

openapi: 3.0.3
info:
  title: ""
  version: ""
paths:
  /things/{id}:
    get:
      parameters:
      - in: query
        name: locale
        schema:
          pattern: ^[a-z]{2}-[A-Z]{2}$
          type: string
      - content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonFilter'
        in: query
        name: json_filter
      - in: path
        name: id
        required: true
        schema:
          example: XXX-XXXXX
          type: string
      responses:
        "204":
          description: No Content
components:
  schemas:
    JsonFilter:
      properties:
        bar:
          type: integer
        foo:
          type: string
      type: object

Another standard alternative is to use deepObject (https://swagger.io/docs/specification/serialization/), with an example of serialization

/users?id[role]=admin&id[firstName]=Alex

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

package main

import (
	"fmt"
	"log"
	"net/http"

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

func main() {
	reflector := openapi3.Reflector{}

	type deepObjectFilter struct {
		Foo string `query:"foo"`
		Bar int    `query:"bar"`
	}

	type req struct {
		ID               string           `path:"id" example:"XXX-XXXXX"`
		Locale           string           `query:"locale" pattern:"^[a-z]{2}-[A-Z]{2}$"`
		DeepObjectFilter deepObjectFilter `query:"deep_object_filter"`
	}

	getOp := openapi3.Operation{}

	_ = reflector.SetRequest(&getOp, new(req), http.MethodGet)
	_ = reflector.Spec.AddOperation(http.MethodGet, "/things/{id}", getOp)

	schema, err := reflector.Spec.MarshalYAML()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(schema))
}

openapi: 3.0.3
info:
  title: ""
  version: ""
paths:
  /things/{id}:
    get:
      parameters:
      - in: query
        name: locale
        schema:
          pattern: ^[a-z]{2}-[A-Z]{2}$
          type: string
      - explode: true
        in: query
        name: deep_object_filter
        schema:
          $ref: '#/components/schemas/DeepObjectFilter'
        style: deepObject
      - in: path
        name: id
        required: true
        schema:
          example: XXX-XXXXX
          type: string
      responses:
        "204":
          description: No Content
components:
  schemas:
    DeepObjectFilter:
      properties:
        bar:
          type: integer
        foo:
          type: string
      type: object