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
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