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.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Mention code reuse via $ref
  • Loading branch information
@luckysori
luckysori committed Sep 3, 2019
commit 7419c39c420c4a7dbdc20e8fe4f5c70f8dcbb6b7
2 changes: 2 additions & 0 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 @@ -54,6 +54,8 @@ It should also be helpful for the team and for newcomers.
OpenAPI, because it appears to be the industry standard, and is compatible with the most tools.
The better human readability of API Blueprint doesn't seem all that important given that these specifications can be viewed using powerful tools such as https://rebilly.github.io/ReDoc/[ReDoc].

Also, OpenAPI's `$ref` keyword would allow us to https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md[reuse] operations (endpoints), responses, parameter lists, etc., which simplifies the task of maintaining both a public API specification for developers and a private one for internal use.

=== How would a developer validate its API usage against the specification? ===

Mock servers powered by tools such as https://connexion.readthedocs.io/en/latest/[Connexion] or https://stoplight.io/prism[Prism].
Expand Down