3 ms·

The naming is completely coincidental and probably a little confusing / unfortunate. OpenAPI is a rebranding of Swagger, a really popular open source API specif

The naming is completely coincidental and probably a little confusing / unfortunate. OpenAPI is a rebranding of Swagger, a really popular open source API specification. Incidentally the OpenAPI initiative only predates OpenAI by a month so I don’t think Sam, Greg & co could have known better at the time. But OpenAPI is the “gold standard” machine readable API specification format so it makes sense that OpenAI would rely on it!

KronisLV 3y ago
> But OpenAPI is the “gold standard” machine readable API specification format I remember when that would have been WSDL, with something like SoapUI - where you'd feed in the service description file from whatever service you want to interact with and would get a functional API client. It also had codegen that let you end up with full client stubs in Java or another language, or are able to generate the WSDL file from your server code as well: https://www.soapui.org/docs/soap-and-wsdl/working-with-wsdls/ https://www.soapui.org/docs/soap-and-wsdl/working-with-wsdls... It's nice to see OpenAPI/Swagger finally catching up, because to me the codegen aspects felt insufficient there for the longest time - if your server code determines what responses to requests it will return, why on earth would you ever want to write the OpenAPI specs manually? It's the same as with ORMs - if you already have a database schema setup on a server somewhere (with SQL migrations, say with dbmate), all of your local entity mappings should be easily generated in a schema-first approach, you shouldn't have to write a single line of code for that. The latest service I'm building is in .NET and they actually have that covered really nicely: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio https://learn.microsoft.com/en-us/aspnet/core/tutorials/gett... And the Rider IDE there also has nice schema-first tooling, even if a bit niche: https://blog.jetbrains.com/dotnet/2022/01/31/entity-framework-core-inside-rider-ui-way/#existing-database-scaffolding https://blog.jetbrains.com/dotnet/2022/01/31/entity-framewor... Model driven development and codegen feel like they definitely belong for boilerplate heavy uses cases like this, where you can also almost perfectly describe the end result that you need based on what you have!
- theryan 3y ago
  Many years ago I was connecting APIs from ~100 companies into our application, they all essentially did the same thing -- update information in our system based on a tracking number. At this time, about half were web APIs and half were WSDLs. The WSDL APIs were by and large the easiest to work with, I didn't have to write much of any code. On the other hand, the web APIs required me to have a custom flow for each and every one and they could break at any point without me knowing. I've seen a lot of hate on WSDLs throughout the years but they were honestly really productive for getting work done.

KronisLV 3y ago

> But OpenAPI is the “gold standard” machine readable API specification format I remember when that would have been WSDL, with something like SoapUI - where you'd feed in the service description file from whatever service you want to interact with and would get a functional API client. It also had codegen that let you end up with full client stubs in Java or another language, or are able to generate the WSDL file from your server code as well: https://www.soapui.org/docs/soap-and-wsdl/working-with-wsdls/ https://www.soapui.org/docs/soap-and-wsdl/working-with-wsdls... It's nice to see OpenAPI/Swagger finally catching up, because to me the codegen aspects felt insufficient there for the longest time - if your server code determines what responses to requests it will return, why on earth would you ever want to write the OpenAPI specs manually? It's the same as with ORMs - if you already have a database schema setup on a server somewhere (with SQL migrations, say with dbmate), all of your local entity mappings should be easily generated in a schema-first approach, you shouldn't have to write a single line of code for that. The latest service I'm building is in .NET and they actually have that covered really nicely: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio https://learn.microsoft.com/en-us/aspnet/core/tutorials/gett... And the Rider IDE there also has nice schema-first tooling, even if a bit niche: https://blog.jetbrains.com/dotnet/2022/01/31/entity-framework-core-inside-rider-ui-way/#existing-database-scaffolding https://blog.jetbrains.com/dotnet/2022/01/31/entity-framewor... Model driven development and codegen feel like they definitely belong for boilerplate heavy uses cases like this, where you can also almost perfectly describe the end result that you need based on what you have!

theryan 3y ago
Many years ago I was connecting APIs from ~100 companies into our application, they all essentially did the same thing -- update information in our system based on a tracking number. At this time, about half were web APIs and half were WSDLs. The WSDL APIs were by and large the easiest to work with, I didn't have to write much of any code. On the other hand, the web APIs required me to have a custom flow for each and every one and they could break at any point without me knowing. I've seen a lot of hate on WSDLs throughout the years but they were honestly really productive for getting work done.