How can I add example for the whole struct

[yurisasuke]

Hello, If I have a struct like below and i want to generate an example for the whole person struct (not each struct individual fields) how can i go about it:

type person struct {
	Name string `json:"name"`
	Message string `json:"message"`
}

The OAS output I would like to achieve is :

   requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
            example:
              name: itachi
              message: sasuke

[vearutop]

Hi, please check an example.

package main

import (
	"fmt"
	"net/http"

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

type p3 struct {
	Name    string `json:"name"`
	Message string `json:"message"`
}

func (p p3) PrepareJSONSchema(schema *jsonschema.Schema) error {
	// Preparer can add and example to the schema.
	schema.WithExamples(p3{
		Name:    "itachi",
		Message: "sasuki",
	})

	return nil
}

func main() {
	reflector := openapi31.Reflector{}
	reflector.Spec = &openapi31.Spec{Openapi: "3.0.3"}
	reflector.Spec.Info.
		WithTitle("Hello World").
		WithVersion("1.2.3")

	// Field examples end up as individual entries for respective properties.
	type p1 struct {
		Name    string `json:"name" example:"itachi"`
		Message string `json:"message" example:"sasuki"`
	}

	// Parent example in JSON format goes to whole parent schema.
	type p2 struct {
		Name    string   `json:"name"`
		Message string   `json:"message"`
		_       struct{} `example:"{\"name\":\"itachi\",\"message\":\"sasuki\"}"` // As of github.com/swaggest/[email protected].
	}

	type req struct {
		P1 p1 `json:"p1"`
		P2 p2 `json:"p2"`
		P3 p3 `json:"p3"`
	}

	oc, _ := reflector.NewOperationContext(http.MethodPost, "/foo")

	oc.AddReqStructure(req{})

	_ = reflector.AddOperation(oc)

	schema, _ := reflector.Spec.MarshalYAML()

	fmt.Println(string(schema))
}

Result

openapi: 3.0.3
info:
  title: Hello World
  version: 1.2.3
paths:
  /foo:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req'
      responses:
        "204":
          description: No Content
components:
  schemas:
    P1:
      properties:
        message:
          examples:
          - sasuki
          type: string
        name:
          examples:
          - itachi
          type: string
      type: object
    P2:
      examples:
      - message: sasuki
        name: itachi
      properties:
        message:
          type: string
        name:
          type: string
      type: object
    P3:
      examples:
      - message: sasuki
        name: itachi
      properties:
        message:
          type: string
        name:
          type: string
      type: object
    Req:
      properties:
        p1:
          $ref: '#/components/schemas/P1'
        p2:
          $ref: '#/components/schemas/P2'
        p3:
          $ref: '#/components/schemas/P3'
      type: object

[yurisasuke]

Hello @vearutop thank you for the quick reply and for creating a great library.

One last question I have is , if a struct (let say p2) is used by two different requests. Is there a way to have different example for the same schema in different requests.

I am looking for output like below:

info:
  title: Hello World
  version: 1.2.3
paths:
  /foo:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/P2'
            examples:
              - message: sasuki
                name: itachi
      responses:
        "204":
          description: No Content
  /anotherPathWithSameStruct:
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/P2'
              examples:
                - message: a different example value for message
                  name: a different exampel value for name
              
components:
  schemas:
    P2:
      examples:
      - message: sasuki
        name: itachi
      properties:
        message:
          type: string
        name:
          type: string
      type: object
    Req:
      properties:
        p1:
          $ref: '#/components/schemas/P1'
        p2:
          $ref: '#/components/schemas/P2'
        p3:
          $ref: '#/components/schemas/P3'
      type: object```

[vearutop]

It is a bit more complicated and also does not work well with $ref.
You can use the actual value when preparing schema, the problem with $ref is that it would be done only on first "visit" of a type, so you'd need to disable reusable definition with InlineJSONSchema().

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

package main

import (
	"fmt"
	"net/http"

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

type p3 struct {
	Name    string `json:"name"`
	Message string `json:"message"`
}

func (p p3) InlineJSONSchema() {}

func (p p3) PrepareJSONSchema(schema *jsonschema.Schema) error {
	// Preparer can add and example to the schema.
	schema.WithExamples(p)

	return nil
}

func main() {
	reflector := openapi31.NewReflector()
	reflector.Spec.Info.
		WithTitle("Hello World").
		WithVersion("1.2.3")

	type req struct {
		P3  p3 `json:"p3"`
		P3A p3 `json:"p3a"`
	}

	oc, _ := reflector.NewOperationContext(http.MethodPost, "/foo")

	oc.AddReqStructure(req{
		P3: p3{
			Name:    "itachi",
			Message: "sasuki",
		},
		P3A: p3{
			Name:    "itachi2",
			Message: "sasuki2",
		},
	})

	_ = reflector.AddOperation(oc)

	schema, _ := reflector.Spec.MarshalYAML()

	fmt.Println(string(schema))
}

Result:

openapi: 3.1.0
info:
  title: Hello World
  version: 1.2.3
paths:
  /foo:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req'
      responses:
        "204":
          description: No Content
components:
  schemas:
    Req:
      properties:
        p3:
          examples:
          - message: sasuki
            name: itachi
          properties:
            message:
              type: string
            name:
              type: string
          type: object
        p3a:
          examples:
          - message: sasuki2
            name: itachi2
          properties:
            message:
              type: string
            name:
              type: string
          type: object
      type: object

[yurisasuke]

@vearutop I have thought of a way I can do this. However what I wonder is can someone add a struct to the component section(#/components/schemas) without necessary adding it via .AddReqStructure or via AddRespStructure().

My thinking is that I can first create all the refs in the component section then I can use operation exposer. to add examples for each path .