I am looking for a way to bring in Swagger Parameter description postman documentation when generating a documentation from collection. I want to bring the details like
“name”
“Description”
“in”
“required”
“type”
Hello there,
Any description you provide for parameters in your swagger definition will be applied upon import as a collection, or used when you generate a collection from the swagger definition using the API builder. Here is an example:
parameters:
- in: path
name: userId
schema:
type: integer
required: true
description: Numeric ID of the user to get
The description for this parameter in the collection will be (Required) Numeric ID of the user to get, which will then be applied when you publish documentation from your collection.
Hope that helps you in your work!
P.S. Also recommend you looking at upgrading from Swagger 2.0 to OpenAPI 3.0, as it has more features and support.
thanks Kin, I have tried below one, but didn’t work, I used OpenAPI 2.0, do you see any issue in below parameter ?
“parameters”: [
{
“name”: “system_name”,
“description”: “System ID”,
“in”: “body”,
“required”: true,
“type”: “string”
},
{
“name”: “id”,
“description”: “ID identifying a single consumer”,
“in”: “body”,
“required”: true,
“type”: “string”
},
{
“name”: “attributes”,
“description”: “Key-Value pairs of consumer data attributes describing the consumer”,
“in”: “body”,
“required”: false,
“type”: “object”
}
],
Hi,
I am looking for answer on how to show parameter on API documentation generated from Postman collection, as of now, I am not able to see any parameters added as below. This is impacting our API documentation release because not showing the data type of parameter and whether it required or not, didn’t add much value.
“content”: {
“application/json”: {
“schema”: {
“$ref”: “#/components/schemas/Consumer”
}
}
},
“description”: “Consumer Object”
},
“Consumer”: {
“description”: “consumer object”,
“properties”: {
“consumer_id”: {
“type”: “string”,
“description”: “Unique ID identifying a single consumer”,
“example”: “xxxxxx-xxxx-xxxx”
},
“souce_system_name”: {
“type”: “string”,
“description”: “System ID, provided for identifying the source of this data”,
“example”: “yyyyyy”
},
“attributes”: {
“type”: “object”,
“description”: “Key-Value pairs of consumer data attributes describing the consumer”
}
},
“required”: [
“consumer_id”,
“souce_system_name”
]
},
Hi, We are looking to release API documentation, but issue of parameter data type and whether parameter is required or not not showing up on Postman API documentation generated from collection is hindering our release of API doc. Looking a help on this.
/v1/consumers/:
post:
operationId: consumer_create
description: Creating Consumers and Modifying the Attributes Stored on Consumers
requestBody:
content:
application/json:
schema:
$ref: ‘#/components/schemas/Consumer’
description: Consumer Object
responses:
‘201’:
description: Successful Post Response
content:
application/json:
schema:
title: Return String
type: string
example: Task added succesfully
tags:
- CX Capture
schemas:
Consumer:
description: consumer object
properties:
consumer_id:
type: string
description: Unique ID identifying a single consumer
example: xxxxxx-xxxx-xxxx
souce_system_name:
type: string
description: ‘Source System ID identifying the source of this data’
example: yyyyyy
attributes:
type: object
description: Key-Value pairs of consumer data attributes describing the consumer
required:
- consumer_id
- souce_system_name
Thanks for more detail. There are several things wrong with this yaml that might prevent it from being read properly. I recommend validating your entire Swagger 2.0 contract using http://editor.swagger.io before trying to import.
You have bad quotes (not sure if it is this forum), plus you can’t have multiple body properties, and should be using a schema for body parameters. All of it combined is likely choking on import.
When I import this resources:
swagger: “2.0”
info:
title: Resource
description: Simple Resource
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
paths:
/resource:
get:
summary: Returns a list of resources.
description: This is the description of the resource.
parameters:
- name: system_name
description: System ID
in: query
required: true
type: string
- name: id
description: ID identifying a single consumer
in: query
required: true
type: string
- name: attributes
description: Key-Value pairs of consumer data attributes describing the consumer
in: query
required: false
type: string
produces:
- application/json
responses:
200:
description: OK
I get imported descriptions:
@mnair I recommend validating your Swagger / OpenAPI using http://editor.swagger.io to make sure it is valid before importing. Craft a complete and valid Swagger / OpenAPI there, and then import to generate collection or API in builder.
thanks @kinlane, had run my current swagger on swagger editor and don’t see any error. Only difference is that I am using Body parameter for Post operation with schema under definition section. Is that stopping from these body parameters getting populated.
/v1/consumers/:
post:
operationId: consumers_create
description: Creating Consumers and Modifying the Attributes Stored on Consumers
parameters:
- name: consumer
description: Consumer Object
in: body
schema:
$ref: ‘#/definitions/Consumer’
responses:
‘201’:
description: Successful Post Response
tags:
- CX Capture
definitions:
Consumer:
description: consumer object
properties:
consumer_id:
type: string
description: Unique ID identifying a single consumer
example: xxxxxx-xxxx-xxxx
souce_system_name:
type: string
description: ‘Source System ID identifying the source of this data’
example: yyyyyy
attributes:
type: object
description: Key-Value pairs of consumer data attributes describing the consumer
required:
- consumer_id
- souce_system_name
My requirement is to show body parameter for Post as required and their data type on documentation… not query parameters