Post Example

[Yaima]

Hi:

• Do you have an example available of how to pass the body parameters using Post?

Thanks

[ok11]

To your point 1: You mean in a swagger definition? If yes, you may want to look here, it's basically only post. Or you mean rather the runtime stuff with JSON marshalling/encoding?

[Yaima]

@ok11 I don't need the swagger definition, but the way to create the spec inside the go code. I want something like this for a POST. With the definition I created, the code is failing and I am not sure what's the best way to specify the body params.

[Yaima]

Maybe an operation will work as well. Is the POST documented somewhere? https://goswagger.io/use/spec/operation.html#example

[casualjim]

it's the same as the get except you use

swagger:operation POST /pets postPet

[Yaima]

@casualjim, that part is clear, how about the body? Are the parameters type: body? Do we need to specify a body object and pass the 2 params in my case?

[casualjim]

yes it's the same. There can only be 1 body parameter so you prefer a schema

You can learn about swagger itself here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

[Yaima]

This is what I did and I am getting this error:
operation (clientCredentials): yaml: line 5: did not find expected key

// swagger:operation POST /token Authentication clientCredentials
//
// Authentication
//
// client_id and client_secret
//
// ---
// produces:
// - application/json
// parameters:
// - name: Body
//  in: body
//  description: **client_id** and **client_secret**
//	schema:
//    "$ref": "#/definitions/Body"
//  required: true
//
//  responses:
//       '200':
// 			description: 'OK'
// 			schema: "$ref": "#/definitions/AuthorizationToken"
//       '401':
// 			description: 'Unauthorized'
// 			schema: "$ref": "#/definitions/ErrorResponse"
router.Post("/token", api.clientCredentials)

[casualjim]

whitespace is significant in yaml

[Yaima]

@casualjim so you are telling me that operation fails because of the spacing? But it doesn't pass the first line. If I name clientCredentials, api. clientCredentials, then the code fails silently skipping this operation.

[Yaima]

@casualjim, the actual file doesn't have white spaces.

[traturne]

Would it be so hard to just provide a concrete example for this? I've literally been searching the documentation for an hour trying to find a good reference to do something simply like specify the POST body in the annotations.

[casualjim]

https://github.com/go-swagger/go-swagger/tree/master/fixtures/goparsing/petstore
https://github.com/go-swagger/go-swagger/blob/master/fixtures/goparsing/petstore/rest/handlers/orders.go#L36-L46
https://github.com/go-swagger/go-swagger/blob/master/fixtures/goparsing/petstore/rest/handlers/orders.go#L80-L102

[nick-phillips-dev]

I had to search the repo to find this. Would be nice to have a more complete example:

@Param <name> body <model> <required> <comment>

e.g.
@Param pet body Pet true "Pet to create"

where Pet would be defined as

type Pet struct {
   Name string `json:"name"`
   ...
}

https://github.com/swaggo/swag/blob/e769bbe213c871a10c6fc64f64dfce47cddce40f/testdata/simple2/api/api.go#L13

[serdmanczyk]

If it's any help I'm doing the markup a slightly different way and here's an example of how I've done it. The body is defined in the models.Application struct. in:body on the parameter field does the trick.

// swagger:route POST /applications applications postApplication
// Creates a new application record.
// responses:
//   200: empty
//   400: error
//   500: error

// swagger:parameters postApplication
type postApplicationParameters struct {
	// in:body
	Application models.Application
}

[skormos]

Not sure if it's a bug, or if it's intentional and is documented somewhere, but I ran into major issues where swagger tags are ignored in comments inside a type ( ... ) block. Rather if the type is assigned it's own type declaration.

So this won't work:

type (
    // MyModel is a model for me.
    //
    // swagger:model
    MyModel struct {
        // required: true
        MyField string `json:"myfield"`
    }
)

But this will:

// My Model is a model for me.
//
// swagger:model
type MyModel struct {
    // required: true
    MyField string `json:"myfield"`
}

I mention it here because it caused serious issues for Parameter declaration as well and seems unclear that a standard Go convention of type blocks wouldn't work.

[toy-lin]

Not sure if it's a bug, or if it's intentional and is documented somewhere, but I ran into major issues where swagger tags are ignored in comments inside a type ( ... ) block. Rather if the type is assigned it's own type declaration.

So this won't work:

type (
    // MyModel is a model for me.
    //
    // swagger:model
    MyModel struct {
        // required: true
        MyField string `json:"myfield"`
    }
)

But this will:

// My Model is a model for me.
//
// swagger:model
type MyModel struct {
    // required: true
    MyField string `json:"myfield"`
}

I mention it here because it caused serious issues for Parameter declaration as well and seems unclear that a standard Go convention of type blocks wouldn't work.

The answer in https://goswagger.io/use/spec/model.html:

Definitions only appear in the generated spec when they are actually used somewhere in the application

[Fly-Away]

Would it be so hard to just provide a concrete example for this? I've literally been searching the documentation for an hour trying to find a good reference to do something simply like specify the POST body in the annotations.

do you have any example of this?

[matheuscamarques]

??????????????

[matheuscamarques]

swagger get body parameters ???

[tbfreitas]

Hey everyone, I got same issue. After spend some time I finally got it. If is someone is getting same error, my approach is showed below:
On endpoint anottation, I inserted

"// @param id body models.NewUserSeller true "User".

Thus, the swagger UI view like a struct object.

Viewing on UI :

I hope it can help someone.

[protonys]

Hey everyone, I got same issue. After spend some time I finally got it. If is someone is getting same error, my approach is showed below: On endpoint anottation, I inserted

"// @param id body models.NewUserSeller true "User".

Thus, the swagger UI view like a struct object.

Viewing on UI :

I hope it can help someone.

Наконец-то реальная помощь! Спасибо!!!

[hunjixin]

it's the same as the get except you use

swagger:operation POST /pets postPet

not work, program regard postPet as operation id.

and can i commet body in this way

	// swagger:route POST /changegroup testflow changetestflow
	//
	// change testflow group id
	//
	//     Consumes:
	//
	//     Produces:
	//     - application/json
	//
	//     Schemes: http, https
	//
	//     Deprecated: false
	//
	//     Parameters:
	//       + name: changGroupRequest
	//         in: body
	//         description: params with group id and testflows
	//         required: true
	//         allowEmpty:  false
	//
	//     Responses:
	//       200:
	//		 503: apiError

generate swager spec success, but when i use this spec to generate client code, get error

- "paths./changegroup.post.parameters" must validate one and only one schema (oneOf). Found none valid
- paths./changegroup.post.parameters.in in body should be one of [header]
- paths./changegroup.post.parameters.type in body is required

how can a comment post parameters?

[casualjim]

I think your route definition is wrong, There is no support for the Parameters like that. You do it in 2 parts (because you can reuse parameters)

To define the route:

https://github.com/go-swagger/go-swagger/blob/master/fixtures/goparsing/petstore/rest/handlers/orders.go#L82-L106

The last argument on that like specifies the id of the operation.

You can then define your parameters as a struct:, the body is a property on there because parameters also capture headers and query params

https://github.com/go-swagger/go-swagger/blob/master/fixtures/goparsing/petstore/rest/handlers/orders.go#L36-L46

If you don't like the model where you need to define a struct, so that type information gets verified by the compiler too, you can use the swagger:operation construct which lets you define the yaml you want verbatim instead of with special comment syntax.

[hunjixin]

@casualjim thanks

[SHU-red]

Hey everyone, I got same issue. After spend some time I finally got it. If is someone is getting same error, my approach is showed below: On endpoint anottation, I inserted

"// @param id body models.NewUserSeller true "User".

Thus, the swagger UI view like a struct object.

Viewing on UI :

I hope it can help someone.

Hi there and thanks for sharing your solution
I got it working to provide a body by providing a type

But in your example it looks like you also were able to add your custom values to your example

This is something i need but could not achieve by now

I can not add a created variable of this type to use values i stored in the variable

Swagger only generates something like this without the possibility for me to change the shown number of items nor the values of the fields/keys

{
  "items": [
    {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  ]
}