flasgger / flasgger/flasgger

Allow OpenAPI 3 "schemas" specification in docstrings (like "definitions" on Swagger 2.0)

Open
#445 1 comment 7 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3.7k
Forks
525
PR merge metrics
No merged PRs in 30d

Description

One nice thing with flasgger and Swagger 2.0 when using docstrings is that you can specify any `definitions` (mostly) specific to one route/path alongside its responses and parameters that may use those.
With OpenAPI 3, those `definitions` moved to `components/schemas`, but it would be great to still specify them in the docstrings of the various routes/paths. There could be a `schemas` entry that we specify there and that gets merged up to `components/schemas` just like `definitions` is for 2.0.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the existing docstring handling for Swagger 2.0 `definitions` and the OpenAPI 3 `components/schemas` path. Confirm that route-level `schemas` entries merge into `components/schemas` while preserving the behavior already provided for `definitions`.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, python
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.