EZP-29977 [Spike] Use RAML for REST API reference - DO NOT MERGE #518
Conversation
MagdalenaZuba
added
Needs DOC review
Needs DEV review
Wait with merge
RAML/ez.raml
Outdated
| description: List the root resources of the eZ Publish installation. | ||
| headers: | ||
| Accept: | ||
| description: application/vnd.ez.api.BookmarkList+xml or application/vnd.ez.api.BookmarkList+json |
There was a problem hiding this comment.
| description: application/vnd.ez.api.BookmarkList+xml or application/vnd.ez.api.BookmarkList+json | |
| description: application/vnd.ez.api.Root+xml or application/vnd.ez.api.Root+json |
RAML/ez.raml
Outdated
| description: Error - if a given location not exists / is not bookmarked | ||
| /Content: | ||
| get: | ||
| description: List the root resources of the eZ Publish installation. |
There was a problem hiding this comment.
| description: List the root resources of the eZ Publish installation. | |
| description: List the root resources of the eZ Platform installation. |
RAML/ez.raml
Outdated
| description: Error - if the user is not authorized to given location | ||
| 404: | ||
| description: Error - if a given location not exists / is not bookmarked | ||
| /Content: |
There was a problem hiding this comment.
Nitpick:
| /Content: | |
| /content: |
we always use lowercase in path elements.
RAML/ez.raml
Outdated
| description: Temporary redirect | ||
| 404: | ||
| description: Error - if the content with the given remote ID does not exist | ||
| /objects/{id}: |
There was a problem hiding this comment.
Nitpick: this might be a good chance to improve readability (either now or as a follow-up). Maybe {contentId} instead, so we exactly know what that is.
RAML/ez.raml
Outdated
| <names> | ||
| <value languageCode="ger-DE">Neuer Titel</value> | ||
| </names> | ||
| <Content href="/content/objects |
There was a problem hiding this comment.
Nitpick: missing end of line, it might be important to some text parsers, that's why GitHub marks it in a specific way.
There was a problem hiding this comment.
This is REST API documentation which I expect as a developer!
The only missing thing is data types spec for request payload and response. Ref. https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#raml-data-types
This PR covers tests for documenting API reference with RAML - DO NOT MERGE
Small section of REST API reference: Bookmark, Content and User was rewritten into RAML.
HTML output was generated from it using raml2html.
links:
how to install RAML: https://www.npmjs.com/package/raml2html
where to get raml2html-material-theme from: https://www.npmjs.com/search?q=keywords:raml2html-theme
command:
raml2html --theme raml2html-material-theme ez.raml > ez.html