Support Swagger v3

[drwpow]

Let’s support Swagger v3!

Should support the data types mentioned here: #92

[milanzivic]

Bump.

Is this enhancement in development? Should we expect it in foreseeable future?

[drwpow]

Hello! I haven’t started working on it yet, but plan to within the month. If anyone has realistic v3 Swagger definitions they’d like me to test, please post them here!

I know that Swaggers docs contain examples, but I’ve usually found those to be too simple and not good for testing support.

[drwpow]

So this library is testing out support of v3 🎉 (see notes), but it’s in beta. Please try this against your existing v3 schema.

If you encounter bugs, please post your full schema here (or the part of your schema that’s giving you trouble if you can’t post the full thing)!

[rikilele]

Hi!
Per company reasons (heavy eye-rolling), I cannot post any of the schemas here, but I am getting a
Cannot convert undefined or null to object error for practically all my valid OpenAPI v3.0.0 specs. Can someone kindly explain to me typical causes for these errors? Thanks in advance!

[tlenex]

Hi, same issue here, just like @rikilele has.
@DangoDev I've invesgtigated it a little and I think the issue is that theres is no more definitions field in v3 spec. It has components instead https://swagger.io/specification/#fixed-fields (v2 for reference: https://swagger.io/specification/v2/#fixed-fields).

[gdspicer58]

Hello,

Same issue as @rikilele , company-reasoned schema censoring and everything.

However, I can provide an example of something that isn't allowed in V2 but is now supported in V3.

{
	"components": {
		"examples": {},
		"headers": {},
		"parameters": {},
		"requestBodies": {},
		"responses": {},
		"schemas": {
			"RoutingTable": {
				"properties": {},
				"type": "object",
				"additionalProperties": {
					"properties": {},
					"additionalProperties": {
						"properties": {
							"routing": {
								"type": "boolean"
							}
						},
						"required": ["routing"],
						"type": "object"
					},
					"type": "object"
				}
			},
			"ContractRequest": {
				"properties": {
					"stateToStateRoutingTable": {
						"$ref": "#/components/schemas/RoutingTable",
						"nullable": true
					}
				},
				"type": "object",
				"additionalProperties": true
			},
			"EmptyBody": {
				"properties": {},
				"type": "object",
				"additionalProperties": true
			}
		},
		"securitySchemes": {}
	},
	"info": {
		"title": "API",
		"version": "v1",
		"description": "A sample API for parsing"
	},
	"openapi": "3.0.0",
	"paths": {
		"/providers/contracts": {
			"post": {
				"operationId": "CreateContract",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/EmptyBody"
								}
							}
						},
						"description": "Ok"
					}
				},
				"summary": "Create a Contract",
				"tags": ["Contracts"],
				"security": [],
				"parameters": [],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/ContractRequest"
							}
						}
					}
				}
			}
		}
	},
	"servers": [
		{
			"url": "https://localhost:3000"
		}
	]
}

For the record, the type of RoutingTable in the TS is this. I'm not saying that the parsed swagger should be like this, but using tsoa rendered the below interface to the above swagger doc.

interface RoutingTable {
	[originValue: string]: {
		[destinationValue: string]: {
			routing: boolean
		}
	}
}

[shivanaru]

Yes, same error and we need this to support the Open API spec or Swagger V3. Thanks!

[drwpow]

Thanks so much for everyone’s input. I’ve started on this this week proper, and when it’s ready I’ll open up an RFC and a test version to make sure it works with your schemas.

I’m already excited with how it’s coming along!

[drwpow]

Update: I’ve started on a 2.0 rewrite that will make supporting Swagger v3 much easier. There’s an alpha branch you can try if you’re curious on your current Swagger v2 schemas (also, feedback welcome):

npx @manifoldco/swagger-to-ts@next …

You can also read more about the improvements here.

I’ll post another message here when this alpha branch supports v3, and open feedback. But the hard part was done in building a base that will work for v2 and v3; now it’s just adding v3 features 🙂

---

Edit: 🤦‍♂️ I wrote swagger-to-ts@alpha before. That’s actually an old build—@next should be what to try (fixed) 👆

[antonk52]

Thanks for your work @DangoDev!

I had trouble trying out the alpha version as shown in the comment above, since the available versions are 2.0.0-alpha.0 and 2.0.0-alpha.1. For other users, if you are running into npm issue with ETARGET error. You can try out the latest version with

npx @manifoldco/swagger-to-ts@next ./path/to/shema.yaml

Now I can see that it generates the *.d.ts file yet it only contains undefined. I will post an update if I happen to figure out why this happens.

[drwpow]

Just published a new @next version that adds basic Swagger v3 support 🤞. I haven’t completely added all the 3.0 features edit: all the basic 3.0 features are supported! 🎉 , except for a question about not (#203).

I’m running it against Stripe’s 3.0 schema and able to build the entire thing.

You can try it out with

npx @manifoldco/swagger-to-ts@next …

🙏 feedback appreciated! Unless anyone experiences issues (in which case please share your schema), I think we’re close to releasing! 🎉

[antonk52]

boy that was quick and impressive! 😎

I've tried it out and I was able to generate some types, but I've run into some issues. It seems that it does not cover the cases when the default value can be null. I've attached a sample schema below with which you can reproduce the issue. I've issued a PR that should fix this

openapi: 3.0.1

info:
  title: sample schema
  version: LATEST

components:
  schemas:
    abstractName:
      type: integer
      format: int64
      nullable: true
      default: null