search

spec-first / connexion

Connexion is a modern Python web framework that makes spec-first and api-first development easy.
https://connexion.readthedocs.io/en/latest/
Apache License 2.0
4.5k stars 765 forks source link

Missing API documentation #1885

Open mivade opened 9 months ago

mivade commented 9 months ago

Description

I was trying to understand how I can customize request body validation but as far as I can tell the docs, while generally very good about describing how to use Connexion, do not appear to contain actual API documentation. In particular the section on custom validators shows how to configure what validator to use but not how to create a custom validator.

Expected behavior

Classes and methods should have browsable API documentation without the need to navigate through Connexion's code itself.

Actual behavior

No API documentation appears to exist.

Steps to reproduce

  1. Visit the documentation on readthedocs
  2. Look for API documentation
  3. Fail to find it

Additional info:

N/A

RobbeSneyders commented 9 months ago

Hi @mivade,

We do have some API documentation embedded throughout the docs. Eg. within the spoilers on this page.

For the abstract validators they're indeed missing though, while I agree they would be useful.

mivade commented 9 months ago

We do have some API documentation embedded throughout the docs. Eg. within the spoilers on this page.

Honestly I hadn't even noticed that. It may be a personal preference but I think having API documentation in a separate part of the documentation makes it a bit more discoverable.