Generate adapter documentation automatically

[krebernisak]

Keeping documentation up to date for adapters is painful, and we should be looking at how to automate this process.

The discussion on the topic started here.

[aalu1418]

Adding a few notes from some research on automated API documentation:

• Swagger specification => OpenAPI spec (OAS)
• Converting inline code comments to OAS using the oas tool (creates a YAML file)
• Another tool (better supported, has CLI): swagger-jsdoc

There seems to be a lot of tools converting from OAS to other readable formats:

• https://openapi.tools/#documentation
• Most generate complete webpages rather than a simple markdown file
• A custom script could be used to create readme documentation from the OAS format?

On a different note, this could be used for autogenerating code documentation (probably not needed for EAs, but maybe in the bootstrap?)

• https://typedoc.org/

[aalu1418]

Current configuration/tools:
Using swagger-jsdoc v6.x as a CLI tool to build OpenAPI spec from code comments.

Command to run (from root):

yarn docgen source coingecko

Example in the coingecko source adapter in the feature/autogen-docs branch.

Next tasks:

• Generate definition.json file automatically for the adapter
• Create proper documentation structure in jsdoc comments (check for inserting environment variable parameters)
• Generate complete OAS spec for one repo (not sure it exactly follows OAS, but it is a somewhat standardized format)
• Remove npx usage? (would speed up process when all files need to autogen docs)
• Front-end visualization of documentation (converting OAS structure to hosted webpages?)

New things to consider:

• Dynamically generating OAS by checking functions/variables in the EA?
• Using jsonnet? (and/or using jsonnet to configure the EA - this requires a lot more revamp of EAs)

UPDATE: See Feautre/autogen-docs PR for the latest

[aalu1418]

New working branch: https://github.com/smartcontractkit/external-adapters-js/tree/feature/autogen-docs-2
Trying to pull parameters directly out of EAs

• Pull endpoint parameters from ./endpoint/*.ts files
• Pull possible endpoints from adapter.ts
• Pull environment variables from config.ts

For full deployment, requires changes to existing EAs to export the necessary parameters

[boxhock]

@austinborn is owning autogenerating documentation on separate stories now