Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

How to document cnd's HTTP API #38

Merged
merged 20 commits into from
Sep 3, 2019
Merged

How to document cnd's HTTP API #38

Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
90cdb10
Start filling in the template
luckysori Aug 27, 2019
aee9bc4
Do the spike
luckysori Aug 29, 2019
aaca50f
Add entry to README.md
luckysori Aug 29, 2019
32aa452
Fix internal links
luckysori Sep 3, 2019
e0b4366
Follow one-line-per-sentence policy
luckysori Sep 3, 2019
16e4698
Fix some periods
luckysori Sep 3, 2019
a227572
Remove duplicated section
luckysori Sep 3, 2019
3c4914f
Use more whitespace
luckysori Sep 3, 2019
dfdc433
Fix image links
luckysori Sep 3, 2019
a32cad3
Actually fix image links
luckysori Sep 3, 2019
505f80f
Embrace manual documentation to take control
luckysori Sep 3, 2019
e4dfc7f
Mention ReDoc custom section support
luckysori Sep 3, 2019
f5f117b
Improve specification generation recommendations
luckysori Sep 3, 2019
7419c39
Mention code reuse via $ref
luckysori Sep 3, 2019
ed0d1dd
Improve extension link relation type section
luckysori Sep 3, 2019
ed6719b
Summarise recommendations at the end
luckysori Sep 3, 2019
e23ed62
Enhance section on elements of the documentation
luckysori Sep 3, 2019
9e2903b
Suggest rather than recommend endpoint name
luckysori Sep 3, 2019
1e0e1ab
Use spike number 16 since 15 was taken
luckysori Sep 3, 2019
b3dfb80
Merge branch 'master' into 1122-document-cnd-http-api
luckysori Sep 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
Prev Previous commit
Next Next commit
Embrace manual documentation to take control
  • Loading branch information
@luckysori
luckysori committed Sep 3, 2019
commit 505f80ff0e4567f168212bb9b12f75e3f2e63dcc
7 changes: 4 additions & 3 deletions 0015-how-to-document-cnd-http-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,10 +157,11 @@ There are https://apisyouwonthate.com/blog/solving-openapi-and-json-schema-diver

==== Recommendation ====

Unfortunately the tools aren't there yet to automatically produce the API specification from source code in Rust.
The tools aren't there yet to automatically produce the API specification from source code in Rust.
There seems to be some interest for this, so it may come in the future.
For the time being, we will have to write it ourselves.
Fortunately, this specification will be <<test-specification,tested>> and we can use tools such as https://speccy.io/[speccy] to validate it.
This may not actually be a problem, since we want to have control over what we show in the specification, in order to motivate the correct use of our REST API from application developers.
To this end, endpoints such as the ones related to actions will probably not be publicly documented.
Additionally, this specification will be <<test-specification,tested>> and we can use tools such as https://speccy.io/[speccy] to validate it.

=== How to visualise specification ===

Expand Down