Changing specs: from Swagger to OpenAPI
Hi all,
Today we're announcing changes to how we serve our API specifications. We'll also be opening a discussion thread on Discord for Q&A and feedback from third-party developers.
Moving forward, we will be publishing our specs as OpenAPI 3.0 and 3.1, and no longer as Swagger 2.0. New updates will be made in the OpenAPI specs only, while we keep Swagger specs in a read-only mode around for a while. We are also introducing a new UI to view the specs.
But why?
OpenAPI 3.0 was introduced back in 2017 and was meant to build upon Swagger 2.0. 2017 was also when the maintainers of the specification rebranded it from Swagger to OpenAPI; in the rest of this blog post, when we say OpenAPI, we mean 3.0 or 3.1. When we say Swagger, we mean 2.0.
Swagger has a few shortcomings that make it hard to express some of our internal structures via ESI. The biggest one is the oneOf statement. For example, say we have a configuration key in a response that can have a value of either destroyShip or deliverItem. In Swagger, there is no way to express this; the best you can do is say the child is either set or null. But does that mean all of them can be null? Or all can be set?
Over the last few years, we have also seen fewer tools support Swagger and more and more tools only support OpenAPI. This became apparent when we were looking for a framework to serve a REST API in Go. The most popular frameworks only support OpenAPI, not Swagger.
Introducing: OpenAPI
To keep up with modern times and to ensure ESI has a long future ahead, we decided to make the change from Swagger to OpenAPI. OpenAPI is structured internally a bit differently, making it more expressive and easier to define reusable components (more on that in a bit). If you want to read more about the difference between Swagger and OpenAPI, Postman wrote an excellent blog about this.
OpenAPI supports oneOf, which will be especially useful for the upcoming Corporation Projects routes. Also, with OpenAPI we can use a framework like Huma, which makes defining API specifications as easy as writing a Go struct. This is a huge difference from our former way of defining API specifications: we wrote those by hand.
As we redefine how we build our API specifications, we also look at the feedback we have on Swagger specs. One of the bigger requests for improvements comes from developers who use generated clients: “make more use of components and reuse where possible”. For example, in the Swagger specs there is more than one place that defines a CharacterID, with all slightly different specifications. With new routes and the power of OpenAPI, Huma, and Go structs, we can solve this. There will be only one global CharacterID, AllianceID, CorporationID… (the list is like 15 long at the moment and will grow over time).
You can already check out the OpenAPI 3.1 specs here (or OpenAPI 3.0 specs here), but consider them beta while we fine-tune them.
Introducing: API Explorer
But why stop there? All third-party developers, at one point or another, have seen the Swagger UI we have been running for the longest time now. But there are actually a few issues with that UI that make it a bit tricky to use. We know because we use it internally every day.
With the introduction of OpenAPI, the Swagger UI either has to be updated, or … maybe replaced? So we looked around to see if we could find other UIs that better fit our wishes.
We ended up finding and falling in love with Stoplight's Elements. This UI is a lot more user-friendly and makes us click a lot less to try out requests. Two features it brings worth mentioning:
If you move from one route to another, and some input fields are shared between them, their value is retained. So if you go to one “characters” route and fill in your CharacterID, it will retain your CharacterID as you move to the next. This is a massive QoL change.
If you copy a URL and link it to someone, that person will actually go to the route you were on, which makes it much easier to show people where to go.
Working on the UI also gave us a moment to reflect whether its location is ideal: currently it sits on esi.evetech.net/ui/, but there are actually also a few routes under that URL. That is a bit confusing. So why not integrate it in the (still somewhat new) developers website? But if we integrate it there, we can also make the whole flow a bit easier. Add a compatibility date selection, make scope selection easier, and make it look more like the rest of the developers website. And so we did. So, without further ado: the new API spec viewer!
Migration
Going forward, new routes will only be added to OpenAPI specs. As such, the Swagger specs will be no longer be updated by us from August 1st on, shortly before the release announcement of Corporation Projects for ESI. We intent to remove the Swagger specs at a later date.
Those of you who mainly use our API spec as a UI reference will see little change. We have a new fancy UI that better structures the information about requests and responses. And we made it easier for you to try out different routes.
The biggest change is for those who use a generated client. Broadly speaking, there are two paths to follow here:
Change/upgrade the tool you use to generate your client to one that supports OpenAPI. This will mean you have to update your application to work with the new generated code, as there will be differences.
Convert the OpenAPI specs to Swagger specs locally, and feed that to your current generator. There are several tools that can do this conversion, both online and offline. Be aware you lose information (like
oneOf) that Swagger doesn't support.
As for the old Swagger UI? By the time you read this, it will automatically redirect to the new UI.
Wrapping up
Although we understand there might be effort on your side switching from Swagger to OpenAPI, we do hope you find it worth the effort. As mentioned, there will be a thread on the EVE Online Discord to discuss these changes, and we are looking forward to hearing your feedback on this.
Cheers,
Your friendly developers of the EVE Swagger Stellar Information (working title)