geopython / geopython/pygeoapi
Enrich OpenAPI parameter descriptions
- Dominant language
- Python
- Stars
- 624
- Forks
- 326
- Avg merge
- 8h 25m
- Merged PRs (30d)
- 2
Description
**Is your feature request related to a problem? Please describe.**
The 'common' parameter descriptions in the generated OpenAPI document (via get_oas_30_parameters() in pygeoapi/openapi.py) are sometimes minimal and could be improved with format guidance and examples. Users relying on tools like Swagger UI have no inline information about expected syntax, default CRS assumptions, or valid value formats. This leads to trial-and-error usage, particularly for spatial and coordinate reference system (CRS) parameters.
**Describe the solution you'd like**
Update the parameter dictionary definitions inside get_oas_30_parameters()
within pygeoapi/openapi.py.
For each parameter (bbox, bbox_crs, crs, offset, skipGeometry) listed:
1. **Expand the description attribute** with clear, concise, and user-friendly
guidance based on the information/examples below.
2. **Add an example or schema/example field** so Swagger UI automatically
populates usable sample values.
**Parameter** - _bbox_
**What's Missing / To Add** - _Axis order, 2D vs 3D format, default CRS, example_
**Example / Guidance to Include** - _minx,miny,maxx,maxy (e.g., -180.0,-90.0,180.0,90.0). Default CRS is WGS 84 (http://www.opengis.net/def/crs/OGC/1.3/CRS84)_
**Parameter** - _bbox-crs_
**What's Missing / To Add** - _URI format requirement, default value_
**Example / Guidance to Include** - _e.g http://www.opengis.net/def/crs/OGC/1.3/CRS84. All reference systems must use the full URI._
**Parameter** - _crs_
**What's Missing / To Add** - _URI format requirement, default value, collection constraints_
**Example / Guidance to Include** - _Must be one of the CRSs advertised in constraints the collection's definitions. All reference systems must use the full URI._
**Parameter** - _offset_
**What's Missing / To Add** - _Example value, clear definition_
**Example / Guidance to Include** - _Integer indicating the starting position for results (e.g., 10)._
**Parameter** - _skipGeometry_
**What's Missing / To Add** - _Short usecase note_
**Example / Guidance to Include** - _Boolean flag to omit geometry in response for performance optimization._
**Describe alternatives you've considered**
**Additional context**
Contributor guide
Assessment
This issue has not been assessed yet.