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
Suggest rather than recommend endpoint name
  • Loading branch information
@luckysori
luckysori committed Sep 3, 2019
commit 9e2903b5eb56b6b40a3ed277b3428c37c159bf63
4 changes: 2 additions & 2 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 @@ -267,7 +267,7 @@ Link: <http:https://example.com/schemas/swap.schema.json#>; rel=”describedby”

* https://apisyouwonthate.com/blog/the-many-amazing-uses-of-json-schema-client-side-validation[Blog on client-side validation based on JSON Schema].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you descrive a bit more OpenAPI vs JSON schema? I am not clear on the concepts.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hopefully clearer now.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What commit made it clearer?

Copy link
Collaborator Author

@luckysori luckysori Sep 5, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one.


=== [[recommend-http-spec-endpoint]] Where to get the specification for the version you are developing against ===
=== [[recommend-use-endpoint-to-host-spec]] Where to get the specification for the version you are developing against ===

Instead of keeping track of all the versions of the API specification and serving all of them remotely, I recommend serving the specification on a local endpoint of cnd's HTTP API, such as `GET /http-spec`.

Expand All @@ -282,4 +282,4 @@ Instead of keeping track of all the versions of the API specification and servin
* <<recommend-host-github-pages, Use GitHub Pages>> to host documentation for latest `master`.
* <<recommend-custom-section-link-relation, Use custom section>> in spec to document extension relation types.
* <<recommend-use-json-schema-more, Embrace JSON Schema>> to describe data.
* <<recommend-http-spec-endpoint, Add `GET /http-spec` endpoint>> to provide documentation for a running instance of cnd.
* <<recommend-use-endpoint-to-host-spec, Add endpoint such as `GET /http-spec`>> to provide documentation for a running instance of cnd.