Comments (4)
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?)
from external-adapters-js.
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
from external-adapters-js.
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
from external-adapters-js.
@austinborn is owning autogenerating documentation on separate stories now
from external-adapters-js.
Related Issues (20)
- Airtable EA Master List updates existing rows properly HOT 1
- Change adapter logs to use a human readable timestamp HOT 1
- Include request host and ip in EA logs & metrics
- Document API reference for @chainlink/ea-bootstrap and @chainlink/types
- Clear environment variables before tests
- Mitigate test memory leak and investigate root cause HOT 1
- Improve clarity of RPC errors
- Use Overrider within ID enabled EAs HOT 1
- Clear test file type errors
- Type check test files
- WS Connections metric decrements into negatives
- Enable metrics by default
- Warn on custom rate limit capacity
- Verify EVM Chain ID
- Sequencer health EA - improve health status verification flow
- Give more information about yarn changeset HOT 5
- Specify instructions to decouple an adapter from monorepo HOT 2
- There is a logic missing in adapter cfbenchmarks's endpoint/crypto-lwba.ts.
- Issue running CoinMarketCap adapter HOT 1
- Section to explain how to generate a list of available adapters in the README
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from external-adapters-js.