I’m continuing my work to help the Department of Veterans Affairs (VA) move forward their API strategy. One area I’m happy to help the federal agency with is just being available to answer questions, which I also find make for great stories here on the blog — helping other federal agencies also learn along the way. One question I got from the agency recently is regarding how the teams should be documenting their APIs, taking into consideration that many of them are supporting legacy services like SOAP.
From my vantage point, minimum viable API documentation should always include a machine-readable definition and some autogenerated documentation within a portal at a known location. If it is a SOAP service, WSDL is the format. If it is REST, OpenAPI (fka Swagger) is the format. If its XML RPC, you can bend OpenAPI to work. If it is GraphQL, it should come with its own definitions. All of these machine-readable definitions should exist within a known location and used as the central definition for the documentation user interface. Documentation should not be hand generated anymore with the wealth of open-source API documentation available.
from DZone.com Feed https://ift.tt/2wtOT9G
No comments:
Post a Comment