Depends on the project I guess. For projects with a defined scope and enough time and money, writing the API first is the way to go, because it enables clear code planning and it's easy to define priorities and see the overall progress of implemented pieces.
However, in real life, most of my projects are experiments. They start out with an idea: "We want to create Something™", and the problem is that we need financing, so we have to blast out the first PoC for the idea in only a couple of weeks. There simply is no time to think about the end-product and plan everything down to the last knob for the first release. That's why I mostly write code first, then generate a documentation from my comments. Hence I have the habit of writing long comments for methods and important classes, explaining what they do and sometimes how they work with other pieces. I even sometimes add examples. It's very agile, because we often have to change code, features or the entire scope, depending on politics and how the product develops and fits in with the stakeholders.
API Design => API Coding => API Doc
We use tools like swagger to do required doc while coding.
I answered Code First, because we generate our specs from the code, but we usually discuss a lot about the design (routes, names, arguments, return values) before to start coding.
This was one of the very reason we choose to use FlaskRestplus (plus ReDoc to customize the rendering and add OpenAPI vendor extensions, like code samples). One of the key point is that it guarantees that the specs we give to our clients is accurate and actually matches the real behavior of the API. We also extended Flask Restplus to provide both public and internal docs. This lets us have «undocumented» endpoints but have the same doc for ourselves (but the scope required to call these is hardly even given to a client, so we hide these endpoints from them)
When we start big features, we even regularly write the code first, which only return 501 Not implemented error, but it let us see the routes, arguments and specs generated live, in the real context, which makes it even much easier to reason about and discuss, see how consistent it is with the rest of the existing endpoints, ...
Another important point for me is that the endpoint documentation is extracted from the implementation comment blocks (and decorators). That means that when we change/extend the implementation -which implies the documentation should also be updated - those 2 pieces are very close to each other in the code base. This brings 2 benefits: it’s much more obvious for the developer to think of the doc update, because of the proximity. And it’s easier for the reviewers to spot missing docs updates, for the same reason.
I know there are auto-generators for API documentation but unsure as to their accuracy. If you do use them - let me know how they go :)
Couple of examples:
pdoc3.github.io/pdoc
laravel-apidoc-generator.readthedocs.io/en/latest
tech.trustpilot.com/an-evaluation-of-auto-generat…
These days, I almost exclusively use Postman to write the API spec before I even start to write the first line of code. Since postman also generates a good looking UI from the spec, it's much easier to share that documentation within the team for feedback and comments.
I've also experimented with writing Protobuf files. The advantage that Protobuf provides is that also allows me to create shared data types and map entity objects across the domain. Unfortunately, Protobuf doesn't have a good documentation generator. Maybe, my next weekend project? :P
I design the API first on the model that's needed. But I don't write it as an open API spec. I write what I need and provide for my customers/clients, then I build the design around it and than I generate it from the code, also usually I provide a client since it's way easier to keep up to date if you just have to update the package.
quite pragmatic in the end.
Writing the documentation is an important part of planning out the layout of the API
Francisco Quintero
Software Engineer & Ruby on Rails Developer
Muhammad Muhajir
Javascript Wizard
Graphql helps alot.