0
# Format Conversion
1

2
Automatic conversion capabilities for transforming Swagger 2.0 and Postman collections to OpenAPI 3.x format, ensuring consistent output regardless of input format.
3

4
## Capabilities
5

6
### Convert Method
7

8
Convert any supported API definition format to OpenAPI 3.x, with automatic detection and transformation of Swagger 2.0 and Postman collections.
9

10
```typescript { .api }
11
/**
12
 * Convert a given API definition to OpenAPI format if it is not already
13
 * Handles Swagger 2.0 to OpenAPI 3.x conversion and Postman to OpenAPI conversion
14
 * @returns Promise resolving to OpenAPI document
15
 */
16
async convert(): Promise<OpenAPI.Document>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import OASNormalize from "oas-normalize";
23

24
// Convert Swagger 2.0 to OpenAPI 3.x
25
const swagger20Spec = {
26
  swagger: "2.0",
27
  info: { title: "Pet Store", version: "1.0.0" },
28
  host: "petstore.swagger.io",
29
  basePath: "/v2",
30
  schemes: ["https"],
31
  paths: {
32
    "/pets": {
33
      get: {
34
        summary: "List pets",
35
        responses: {
36
          "200": {
37
            description: "Successful response"
38
          }
39
        }
40
      }
41
    }
42
  }
43
};
44

45
const oas = new OASNormalize(swagger20Spec);
46
const openapi = await oas.convert();
47

48
console.log(openapi.openapi); // "3.0.3" (or similar)
49
console.log(openapi.servers); // [{ url: "https://petstore.swagger.io/v2" }]
50
```
51

52
```typescript
53
// Convert Postman collection to OpenAPI
54
const postmanCollection = {
55
  info: {
56
    name: "Pet Store API",
57
    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
58
  },
59
  item: [
60
    {
61
      name: "Get Pets",
62
      request: {
63
        method: "GET",
64
        url: "{{baseUrl}}/pets"
65
      }
66
    }
67
  ]
68
};
69

70
const oasPostman = new OASNormalize(postmanCollection);
71
const openapi = await oasPostman.convert();
72

73
console.log(openapi.openapi); // "3.0.0"
74
console.log(openapi.info.title); // Derived from Postman collection
75
```
76

77
```typescript
78
// OpenAPI definitions pass through unchanged
79
const openapi31Spec = {
80
  openapi: "3.1.0",
81
  info: { title: "Already OpenAPI", version: "1.0.0" },
82
  paths: {}
83
};
84

85
const oasAlready = new OASNormalize(openapi31Spec);
86
const result = await oasAlready.convert();
87
// Returns the same object (no conversion needed)
88
```
89

90
## Supported Source Formats
91

92
### Swagger 2.0
93

94
Converts Swagger 2.0 specifications to OpenAPI 3.x format using the `swagger2openapi` library:
95

96
```typescript
97
// Input: Swagger 2.0
98
const swagger = {
99
  swagger: "2.0",
100
  info: { title: "API", version: "1.0" },
101
  host: "api.example.com",
102
  basePath: "/v1",
103
  schemes: ["https"],
104
  definitions: {
105
    Pet: {
106
      type: "object",
107
      properties: {
108
        name: { type: "string" }
109
      }
110
    }
111
  },
112
  paths: {
113
    "/pets": {
114
      get: {
115
        responses: {
116
          "200": {
117
            description: "Success",
118
            schema: { $ref: "#/definitions/Pet" }
119
          }
120
        }
121
      }
122
    }
123
  }
124
};
125

126
// Output: OpenAPI 3.x equivalent
127
const converted = await new OASNormalize(swagger).convert();
128
// Results in:
129
// - openapi: "3.0.3"
130
// - servers: [{ url: "https://api.example.com/v1" }]
131
// - components.schemas.Pet (moved from definitions)
132
// - Updated response schema references
133
```
134

135
**Key Swagger 2.0 Conversion Features:**
136
- Host + basePath + schemes → servers array
137
- definitions → components.schemas
138
- parameters → components.parameters (when referenced)
139
- responses → components.responses (when referenced)
140
- securityDefinitions → components.securitySchemes
141
- Schema references updated to new format
142

143
### Postman Collections
144

145
Converts Postman Collections (v2.0/v2.1) to OpenAPI format using `@readme/postman-to-openapi`:
146

147
```typescript
148
// Input: Postman Collection
149
const postmanCollection = {
150
  info: {
151
    name: "My API",
152
    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
153
  },
154
  variable: [
155
    { key: "baseUrl", value: "https://api.example.com" }
156
  ],
157
  item: [
158
    {
159
      name: "Create User",
160
      request: {
161
        method: "POST",
162
        url: "{{baseUrl}}/users",
163
        header: [
164
          { key: "Content-Type", value: "application/json" }
165
        ],
166
        body: {
167
          mode: "raw",
168
          raw: '{"name": "John", "email": "john@example.com"}'
169
        }
170
      }
171
    }
172
  ]
173
};
174

175
const converted = await new OASNormalize(postmanCollection).convert();
176
// Results in OpenAPI 3.x with:
177
// - Inferred schemas from request/response examples
178
// - Authentication schemes from Postman auth settings
179
// - Path parameters from URL templates
180
```
181

182
**Key Postman Conversion Features:**
183
- Request/response examples → schema inference
184
- Postman variables → server variables or examples
185
- Authentication settings → security schemes
186
- Folder structure → OpenAPI tags
187
- Pre-request scripts and tests → ignored (not applicable)
188

189
### OpenAPI (Pass-through)
190

191
OpenAPI 3.x specifications are returned unchanged:
192

193
```typescript
194
const openapi = {
195
  openapi: "3.1.0",
196
  info: { title: "Already OpenAPI" },
197
  paths: {}
198
};
199

200
const result = await new OASNormalize(openapi).convert();
201
// Returns identical object - no conversion performed
202
```
203

204
## Error Handling
205

206
### Unsupported Formats
207

208
```typescript
209
const unsupportedSpec = {
210
  // Missing swagger, openapi, or Postman collection indicators
211
  info: { title: "Unknown format" }
212
};
213

214
try {
215
  await new OASNormalize(unsupportedSpec).convert();
216
} catch (error) {
217
  console.error(error.message); // "The supplied API definition is unsupported."
218
}
219
```
220

221
### Swagger v1.2 Rejection
222

223
```typescript
224
const swagger12 = {
225
  swagger: "1.2",
226
  info: { title: "Old Swagger" }
227
};
228

229
try {
230
  await new OASNormalize(swagger12).convert();
231
} catch (error) {
232
  console.error(error.message); // "Swagger v1.2 is unsupported."
233
}
234
```
235

236
## Integration with Other Methods
237

238
The convert method works seamlessly with other OASNormalize methods:
239

240
```typescript
241
const swagger = { swagger: "2.0", /* ... */ };
242
const oas = new OASNormalize(swagger);
243

244
// Convert, then validate the result
245
const openapi = await oas.convert();
246
await new OASNormalize(openapi).validate();
247

248
// Or validate the converted result directly
249
await oas.validate(); // Internally converts first if needed
250
```
251

252
## Conversion Options
253

254
The conversion process uses default settings optimized for compatibility:
255

256
- **Swagger conversion**: Uses `swagger2openapi` with anchors enabled for better $ref handling
257
- **Postman conversion**: Uses JSON output format with variable replacement enabled
258
- **No Caching**: Unlike other methods, convert() does not cache results and will perform conversion on each call
259

260
```typescript
261
// The conversion is NOT cached - each call performs the conversion
262
const oas = new OASNormalize(swaggerSpec);
263
const first = await oas.convert();   // Performs conversion
264
const second = await oas.convert();  // Performs conversion again
265
console.log(first === second); // false (different object instances)
266
```