6 ms·

How do you keep your services Api documentation updated in your organization? Are you generating openapi specs directly from code? Or do you build it with a ui

How do you keep your services Api documentation updated in your organization? Are you generating openapi specs directly from code? Or do you build it with a ui designer tool like this ? Creating the documentation is a hard, but having developers keep updating it is even harder. And if it's not updated regularly, it loses its value quickly

Nijikokun 6y ago
Great question. We do believe in Design First Development, where the idea is designed out with the key party members as a part of that group. In this case, it could be the Lead Architect, or Team Lead, or Individual Contributor starting the specification and working closely in source control / pair programming to define that first draft to prevent things tech debt, refactoring, recoding, etc. Once it's agree'd upon and merged into the codebase, we believe from there, should you setup a pipeline to have it be updated from the codebase, which commits to the repository, that should be allowed as long as the process is kept. So you still have tests against your specification that ensure your implementation works as described, and your specification is validated and enforced with the right policies. We have some known gaps around policy enforcement and placement that we intend to correct soon. But, this is our belief. As far as UI driven design, or Text driven design, I personally believe that both can be achieved. Not everyone knows these specifications and having an interface can on-board those individuals and get them ramped up quickly to service the needs and demands of the business. Where the text form is useful for advanced users, quick changes, automation pipelines, testing frameworks, diff checking, and so forth. So we don't want to ultimately get rid of that layer either. I think the best approach will be some form of a balancing act. Would love to hear feedback on this.
- mderazon 6y ago
  Thank you for the reply, For node.js, so far I haven't found any good tool to generate openapi specs from code. If by chance you have recommendations I would be happy to know some other complimenting tooling for it

Nijikokun 6y ago

Great question. We do believe in Design First Development, where the idea is designed out with the key party members as a part of that group. In this case, it could be the Lead Architect, or Team Lead, or Individual Contributor starting the specification and working closely in source control / pair programming to define that first draft to prevent things tech debt, refactoring, recoding, etc. Once it's agree'd upon and merged into the codebase, we believe from there, should you setup a pipeline to have it be updated from the codebase, which commits to the repository, that should be allowed as long as the process is kept. So you still have tests against your specification that ensure your implementation works as described, and your specification is validated and enforced with the right policies. We have some known gaps around policy enforcement and placement that we intend to correct soon. But, this is our belief. As far as UI driven design, or Text driven design, I personally believe that both can be achieved. Not everyone knows these specifications and having an interface can on-board those individuals and get them ramped up quickly to service the needs and demands of the business. Where the text form is useful for advanced users, quick changes, automation pipelines, testing frameworks, diff checking, and so forth. So we don't want to ultimately get rid of that layer either. I think the best approach will be some form of a balancing act. Would love to hear feedback on this.

mderazon 6y ago
Thank you for the reply, For node.js, so far I haven't found any good tool to generate openapi specs from code. If by chance you have recommendations I would be happy to know some other complimenting tooling for it