Cover image by Mattia Serrani on Unsplash.
With software products being more and more just a bunch of micro-services and third-party APIs mashed t...
For further actions, you may consider blocking this person and/or reporting abuse
There are also several frameworks that will generate OpenAPI specs from the implementation. Sort of turns the whole process on its head, but its a great workflow for, say, a Python developer who is very comfortable writing in their framework of choice but doesn’t want to learn the OAS DSL.
FastAPI and Flask-Restplus are the two I use. Great for writing the API in Python then taking advantage of OAS to generate client libraries.
Good to know!
I read about GraphQL frameworks moving from schema-first design to creating schemas from the implementations, or even directly from the database schema.
Nice that such tools also exist for OpenAPI!
Yep. I do development in .NET Core and we can generate OpenAPI spec from code using NSwag or Swashbuckle. Very easy.
I'm currently working at a company where there is an API first approach, using REST with open API. It seems a great idea, especially to control the public APIs. However, especially compared to GraphQL there are several things not so nice.
If your using advanced features, the Java generation doesn't always produce the correct result. Which means you need go back to a simpler way, less well describing the API.
Although we put authorizations in the definition, they are not shown in the tool used to inspect the API. Also because of the authorizations you can't test the endpoints from the tool. Worse is, besides testing, there is no enforcement on implementing the correct authentications.
If you want to know what's available at a certain environment, you need to know which version of the generated API is used there. While with GraphQL you could just inspect the endpoint.
I also worked with REST without using either OpenAPI or swagger, and that was a lot worse. As we had to make sure the manual written documentation was kept in sync with the actual implementation.
Yes, I also read that the generated code is often awful.
Awful would be great. But as soon as you start using things like anyof etc. it becomes unusable. I might give it a try some day to make it better. It would be very nice if it was better supported, and for example when creating GraphQL based on OpenApi it could also use all of this information.
In the javascript ecosystem, NestJS is absolutely amazing to work with when generating an OpenAPI document.
As it’s based off typescript, you can add property decorators to your models, and it simply works when you create your endpoints!
See for yourself on their documentation.
Didn't know NestJS used OpenAPI!
Question, Is there an easy way to set up the authentication and billing systems around APIs? I think, several times that is way harder to do than designing the actual API.
I had the impression most frameworks would offer auth integrations.
But payment often is a problem. Sometimes you get a basic plugin, but getting the payment-flow right requires to dig so deep that you end up implementing the stuff almost from scratch.
I now remember we used tyk.io/ at my previous workplace.
My experience with openapi,
The specification was good but swagger tools sucks.
openapi + postman = awesome
Any other tool recommendations? I would expect using OpenAPI directly is a bit cumbersome.
Looks great. I'll check it out.
Note that OpenAPI also assists in generating clients. This enables, much like other IDLs, the server provider to support clients in a multitude of languages without a large increase in cost. :)
You're totally right!
If you build an API SaaS company, having clients for all the popular languages can be very important, getting this from OpenAPI can save money and time!