Structure to support both OpenAPI and Postman format to upload as Collections

New to APIs/Postman
,
1

I have a new project. I am arranging the api format to use as openapi and postman. I would prefer to use the same file to upload both openapi supported tools like Readme and Postman without any manual editing or conversion.

Please share the details on bestest practices, directory structure and naming conventions

2

Hey @subeeshes :wave:

Welcome to the Postman Community! :postman:

Could you provide an example of what you have already?

I’m not sure of the format or structure of Readme to know what that looks like.

In terms of Postman, you can import either a openapi schema or a Postman Collection.

3

Thank you Danny for the response.

Here is our existing API documented at Readme: Finds approximate location by IP.
json code Snippet for this is shared below.

Above using swagger(openapi)

The requirement is to use the same OpenAPI json file to also upload to Postman collections using “postman” or curl command automatically. However, to do that, we have to use a converter(openapi2postmanv2) and manual editing to upload a collection.
hence, we would like to know, how to format our openapi to support postman.

=== snippet of the json file we have now==


{
  "swagger": "2.0",
  "info": {
    "title": "IP Location service",
    "description": "Provides approximate city-level location, country, timezone, and mapping geo-coordinates for an IP address using statistical models.",
    "version": "1.0.3",
    "contact": {
      "name": "Fastah Support",
      "url": "https://docs.getfastah.com",
      "email": "[email protected]"
    }
  },
  "tags": [
    {
      "name": "location",
      "description": "Location-related API"
    }
  ],
  "schemes": [
    "https"
  ],
  "host": "ep.api.getfastah.com",
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "API Key as HTTP header": {
      "type": "apiKey",
      "in": "header",
      "name": "Fastah-Key"
    },
    "API Key as Query parameter": {
      "type": "apiKey",
      "in": "query",
      "name": "fastah-key"
    }
  },
  "security": [
    {
      "API Key as HTTP header": []
    },
    {
      "API Key as Query parameter": []
    }
  ],
  "paths": {
    "/whereis/v1/json/{IP}": {
      "get": {
        "tags": [
          "location"
        ],
        "operationId": "getLocationByIP",
        "summary": "Finds approximate location by IP.",
        "description": "Use this API for mapping an IPv4 or IPv6 address to city name.",
        "produces": [
          "application/json"
        ],
4

Have you tried using the Import feature in Postman which the openapi file to create a Postman Collection?

Screenshot 2025-03-05 at 10.19.33
Screenshot 2025-03-05 at 10.19.331832×908 46.2 KB

5

Yes, import option was tried. It imports and creates a new collection everytime. However, we want to update the existing collection everytime per every release of our product using automation.

Here is what is needed:
We have tried to upload to postman with openapi2postmanv2 and then adding the “collection” tag, etc and it is a bit lengthy step.
Hence, looking for a json format which is suitable to update our existing project and also for our upcoming project.

Is there a commandline to convert the openapi format to a postman collection ? If yes, what should be the structure of the openapi json file to support this seemless conversion.

You may also share some open source projects following fully automated postman uploads to use as a reference.

6

The structure of an openapi schema is quite a defined one already.

You could use the Postman API to programmatically import the schema:

There are also other endpoints that can assist you with updating an existing Collection rather than importing and creating a new one each time.

7

Thank you Danny!. We will try this as you suggested.