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

[jfsiii]

Thanks for all the work on this @DangoDev!

I had some issues with this file

$ npx @manifoldco/swagger-to-ts@next ./spec.json
npx: installed 69 in 5.559s
🤞 Loading spec from ./spec.json…
SyntaxError: ',' expected. (9:127)
   7 | export interface components {
   8 |     schemas: {
>  9 |     "AgentConfig": components['schemas']['NewAgentConfig'] & {"id":string,"status":'active' | 'inactive',datasources?:[object Object] | [object Object],updated_on?:string,updated_by?:string};

components.schemas.AgentConfig from spec.json

      "AgentConfig": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NewAgentConfig"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "inactive"
                ]
              },
              "datasources": {
                "oneOf": [
                  {
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "items": {
                      "$ref": "#/components/schemas/Datasource"
                    }
                  }
                ],
                "type": "array"
              },
              "updated_on": {
                "type": "string",
                "format": "date-time"
              },
              "updated_by": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "status"
            ]
          }
        ]
      },

I changed it to an array of strings and ran it again. This time the result was

SyntaxError: Invalid character. (13:230)
  11 | "NewAgentConfig": {name?:string,namespace?:string,description?:string};
  12 | "NewDatasource": {enabled?:boolean,title?:string,package?:{"name":string,"version":string},namespace?:string,"use_output":string,"inputs":{id?:string,enabled?:boolean,dataset?:string,metricset?:string,paths?:string[]}[]};
> 13 | "PackageInfo": {"name":string,"title":string,"version":string,readme?:string,"description":string,"type":string,"categories":string[],"requirement":{kibana?:{versions?:string}} | {elasticsearch?:{versions?:string}},screenshots?:{\"src\":string,title?:string}[],icons?:string[],"assets":string[],internal?:boolean,"format_version":string,datasets?:{\"title\":string,\"name\":string,\"release\":string,\"ingeset_pipeline\":string,vars?:{\\\"name\\\":string,\\\"default\\\":string}[],\"type\":string,\"package\":string}[],"download":string,"path":string};
     |                                                                                                                                                                                                                                      ^

PackageInfo.properties.screenshots in spec.json

"screenshots": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "src": {
        "type": "string"
      },
      "title": {
        "type": "string"
      }
    },
    "required": [
      "src"
    ]
  }
},

That's when I figured I should stop and send this to you :) Hope that helps. Let me know if there's anything I can do. I'm excited to see v3 -> types!

[drwpow]

@jfsiii thanks for the example file! That’s all I need to fix this. I’m sure it’s just a minor thing somewhere. Also thanks for taking time to test

Would you be OK if I included your schema as part of this library’s tests? That way we can be sure that future changes are tested. But if you’re not comfortable with that I can always just abstract parts of it into the unit tests.

[drwpow]

@jfsiii OK found the issue: this library was expecting { type: 'array', items: { … } }, but got only { items: { … } } (no type). That’s fixed, and what was causing an error in your schema.

Also under PackageInfo.requirement, there’s an empty object ({}) in oneOf that was also causing an error. Not sure if that’s intentional or not, but I decided to resolve that to { [key: string]: any } (basically, an object of unknown shape).

This has been pushed in the latest pre-release, which you can try with:

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

[jfsiii]

@DangoDev thanks for that. I see now that the input file was invalid.

The generated types look great! I noticed they only contain components.schemas; any plans for components.parameters?

[drwpow]

any plans for components.parameters?

There are now! I’m thinking maybe that’ll be the last addition for the swagger-to-ts 2.0 before a stable release. Added tests for all the shiny new OpenAPI 3.0 features, and I think I’ll release a new major version once that’s in.

[drwpow]

On second thought, this seems to be part of the paths addition. I’ve added #236 to keep track of this addition.

I think because that’s actually a major addition to the library (that I agree with), I’ll release the 2.0 of this library now to get out OpenAPI 3.0 support sooner. And we can work on adding paths to both OpenAPI 2.0 + 3.0 in a followup minor release. Agreed that it would be a helpful addition!

[drwpow]

@manifoldco/[email protected] released and is live on npm! 🎉 Thanks so much for everyone here that participated in discussion, and helped raise issues to get us to this point.

I’m going to close this issue. I believe I’ve taken care of everything raised here, but please open another issue on this library if I missed something. Thank you all! 🙏