USACE / USACE/cwms-data-api

Locations POST has incorrect required fields in Swagger Spec

Open
#1,091 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

swagger-spec
Dominant language
Java
Stars
28
Forks
25
Avg merge
4d 22h
Merged PRs (30d)
20

Description

Incorrect swagger spec requirements for POST Locations

The Locations POST for CDA asks for name and office as required fields

However, when you make a post body of that content you get this error back:

CURL:

curl -X 'POST' \  
'https://SWT-T7:TC-Port/swt-data/locations' \ 
 -H 'accept: */*' \  
-H 'Content-Type: application/json' \  
-d '{  "office-id": "SWT",  "name": "TestLoc_MDP"}'

RESPONSE:

{  
"message": "required fields not present",  
"incidentIdentifier": "user input error",  
"details": {    
  "missing fields": [     
     "horizontal-datum",      
     "timezone-name",     
     "latitude",      
     "location-kind",      
     "longitude"    
    ]
  }
}

Seems it was just forgotten to be added to the swagger spec.

But this is important not only for swagger but also for generators that enforce requirements BEFORE the API call gets made and wasted on a response stating what the wrapper library could have stated.

But this also confused an end user trying to build something into their python code and trying to figure out required fields.

Suggest a single PR to cross check endpoints and cleanup the spec of required fields?

Contributor guide

Open the contributing guide

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.

Research direction

Locate the Swagger/OpenAPI definition for POST /locations and compare its required fields with the backend validation response shown in the issue. Update the contract to include the missing fields, then audit related endpoint requirements; done when the specification matches validation and generated clients can identify all required inputs before making the request.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.