TODO: Convert from brain dump to polished article

This idea came out of Rails as an HTML container, specifically the Obfuscation layer section. Using rswag is the perfect example - in adding a dsl to your openapi.yml spec, you get pretty-ness (because you're writing ruby), but you dramatically increase the maintenance burden, because now your team needs to read two sets of docs in order to work on anything related to your API docs. Additionally, you will find it much more difficult to assign a simple task like "Add a new parameter and response to our API docs" to a less experienced developer.

This is of course a subjective opinion, and one you should only adopt if keeping your codebase simple and novice-friendly is a priority for you.