Example Snippet Generator¶
Launchpad blueprint:
https://blueprints.launchpad.net/trove/+spec/example-snippet-generator
Problem Description¶
Trove has ssome really nice documentation featuring snippets showing the what the JSON looks like for the standard REST calls and response. The only issue is these docs are not validated, meaning if the API changes in ways big or small its possible they will not match what a present day user of Trove will see.
Proposed Change¶
This blueprint proposes we fix this by automatically generating these examples and validating them in Trove.
The fix will involve actually making calls against the real Trove code and capturing the bodies of the requests and responses then writing them to the text files used by the docs. We can do this quickly by utilizing the same “fake mode” test doubles that are used by the tests already run in Tox. The beauty is all of the API code that determines what the request and responses look like will get run just the same as if the tests had executed against a fully stood up Trove environment, with the advantage that certain UUIDs can be altered to avoid them changing with every test run.
Configuration¶
None
Database¶
None
Public API¶
None
Public API Security¶
None
Internal API¶
None
Guest Agent¶
None
Data Model Impact¶
None.
REST API Impact¶
None, except that it will be tested even better than before.
Security Impact¶
None.
Notifications Impact¶
None.
Other End User Impact¶
None.
Performance Impact¶
The snippet generation will run in mere seconds as part of Tox. There will be no noticeable impact on the developers of Trove.
Other Deployer Impact¶
None.
Developer Impact¶
The generation will run fast enough to be invisible to most developers. However developers will be aware if they inadvertently change anything in the request or response payload and will have to argue for the changes to the API, even if they’re merely additions.
Community Impact¶
The generation of snippets will usher in a new golden era of devs and doc writers working together. Maybe sometimes devs will be doc writers, or doc writers will be devs. It isn’t a stretch to suggest it will be a utopia.
Alternatives¶
We could continue the implied agreement that devs are always constantly reading the docs and treating that as a contract, and that with each change they rabidly run integration tests but also manually run tests and inspect the output, making sure the snippets shown in the docs are accurate. Unfortunately since many of the current snippets are inaccurate I don’t think this will work.
Implementation¶
Assignee(s)¶
- Primary assignee:
Tim Simpson
Milestones¶
- Target Milestone for completion:
Kilo-1
Work Items¶
Implement the snippets generator.
Dependencies¶
None.
Documentation Impact¶
We will need to change the snippets at least initially as they have changed so much since when they were originally authored.
User Documentation¶
None.
Developer Documentation¶
We will need to document how this works in the Tox file.
