Sometime, real API and documentation have deep groove. So I have decided to create document from real API request and response. At first, I have created swagger from API response. After that, I have published mkdocs documents from swagger. Many developers wrote the API document in the source code. But we need more information in the document such as sample code, example parametors and more. So sometime source readability is down by API information. I recomend we should write the API information in test code.
Another case, I have to support English and Japanese version of API document. I have a swagger file written by English. I made a small script file that load swagger file and translation key files, and it generates the documents both languages. Most swagger or OAS tools don’t support internationalization. But some developers need it like Japanese, Chinese and etc. Translation key file is very simple solution.