Dynamically generated Swagger Documentation for REST / JSON API

Open
  • Is something wrong?
#621 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
openapi, python
Domain
api, documentation

Research direction

The issue names no files, tests or entry points, so begin by finding how the REST framework currently exposes its routes and whether it already emits any OpenAPI or Swagger output. Settle the design first: which modules and endpoints the generated spec should cover, and how it is served per installation. Done means a maintainer-agreed design and a generated spec that matches a running instance.

Written by the indexing model from the issue text.

Description

enhancement

Is your feature request related to a problem?
As a developer that is still fairly new to Odoo in general I feel an unfulfilled need for clear guidance on the JSON API that is not met in the current documentation.

Describe the solution you'd like
If there would be swagger documentation for the REST API that gets created dynamically based on your own url and modules installed, this would be such an improvement from my point as a developer.

NocoDB has a feature like this. You create a base, you add tables, columns,... And it just spits out dynamic, interactive developer docs.

From a developer point of view that allows to have a working API Reference for my specific installation without it forcing me to first learn the internals and code base of all models.

Describe alternatives you've considered
Both trying to set this up in own code or n8n, it all flows through the JSON API. In both cases (odoo docs and n8n docs) the documentation is sparse. I could go through the actual models in the backend code and translate that info to how it would work in REST.

It does force me to be aware of all internals of Odoo and the internal codebase before I can attach to it (properly) from the outside. I think improving the developer experience for external connections is a better path of entry than asking developers to understand (and possibly start making edits to) the internals.

Additional context

I'm trying to get our dealerplatform (not on odoo) to generate a sign request in Odoo for new quotes that are being generated. I couldn't find clear REST API documentation so I choose to implement it through n8n thinking it would clear things up. It's just some CRUDs after all. The experience there isn't that much better than manually coding it.

The fact that it runs through n8n at this point is irrelevant for the proposed feature.

I've got a pdf uploaded, it's an attachment. I also made a signature template and created a document with that attachment in that template. Then I create a contact and now.... I create a sign request? it keeps failing, I'm sure it's expecting more of me, but I don't have a clear view what the API expects of me.

Dominant language
Python
Stars
385
Forks
393
Avg merge
4d 22h
Merged PRs (30d)
21

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OCA/rest-framework

All issues in OCA/rest-framework

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.