OpenAPI definitions have a lot of nuances that most of us can’t be bothered to learn right away. This is often the way of the developer—jumping into a new technology and trying to hack it out until it looks right and hopefully works. However, we often stumble and end up reading the documentation anyway, just enough to get the job done. A better approach is to try to minimize the amount of documentation we actually need to know by building tools that can help guide our actions.
Swagger Editor is one such tool for writing OpenAPI definitions. It is a web application hosted at https://editor.swagger.io, or it can be downloaded and self-hosted. Like a lot of Swagger tools, it is open source. The web application contains both a text editor and a panel showing the generated documentation. The documentation pane shows the results of what we type, giving us immediate feedback and a great affirmation that we typed the right things. We also get validation on the definition, which means that if we type something incorrectly, it’ll shout at us and (hopefully) give us insight into fixing it. It is primarily used as a design tool (see figure 4.1).
