Skip to content

Polish resource schemas and update documentation

Johannes Zumthurm requested to merge doc_overhaul into master

Created by: NotSpecial

This commit greatly adds functionality to the online documentation and generally improve the documentation of all resources.

While I have updated the required and default properties of some fields, as far as I am aware there should be no breaking changes.

I took this as a chance to clean up the schemas and fix some inconsistencies, which I'll explain below.

General updates:

  • Moved the DocValidator, which defined dummy rules for description etc. into the main validator. Rationale: Whether or not the online docs are activated, the descriptive schema is useful. Furthermore, deactivating the documentation should not cause problems with all schemas (because of missing validation rules).
  • The API now adds definitions for all internal fields to the schema, i.e. _etag and so on. Eve already did this for the _id field, so I extended it (mainly such that the online documentation can include it nicely).
  • To be consitent with item titles, resource titles are now capitalized too.

Schema updates:

  • Enforced more consistency with required- and default-values. Every field now has to be either required xor needs a default value. If the field has a default value, there is no need for it to be required, but if it hasn't, the user must provide it. This is mainly done to remove confusion around missing values. This is supported by Eve (and MongoDB), but serves no practical use for use, yet can create confusion.
  • Updated the required status of fields appropriately, added defaults where needed.
  • Re-worked all field and resource descriptions to cover (hopefully) all functionality. Also added examples for all fields.
  • In particular, added extensive descriptions behind the purpose of each resource, integrating the previous effort on the 'API purpose documentation'.
  • For some resources like oauthclients, added proper resource and item titles (e.g. OAuth Client).

Documentation updates:

  • Removed outdated developer and admin documentation.
  • Moved documents such as the Cheatsheet or the OAuth user guide into the online docs, which are now the 'single source of truth' for users.
  • Extended the Cheatsheet to cover sending data with multipart/form-data
  • Added general introductions to REST and API auth.
  • In the online docs, added support for:
    • Query parameters.
    • Authorization header.
    • Additional lookup path for GET.
    • Error Responses.
  • Hooks are not displayed anymore, as they are only relevant for API developers and not for users.
  • Updates ReDoc to version 2.

Regarding the documentation updates, I briefly considered putting them into a pull request to Eve-Swagger. However, development on Eve-Swagger seems stale, with two open pull requests without response. Furthermore, most additions include AMIV API specific detail (e.g. a link to the cheatsheet), so I opted for a API specific solution instead.

This commit resolves the last open issues for version 2.0.0:

Resolves #119 (closed) Resolves #137 (closed) Resolves #168 (closed)

Merge request reports