OpenAPI definition issues
issues i encountered in the current version of https://sshoc-marketplace-api.acdh-dev.oeaw.ac.at/v3/api-docs
-
getInformationContributors
don't have unique operation ids, i.e. it's named the same for every category, so we end up withgetInformationContributors_1
,getInformationContributors_2
etc. Same for thegetInformationContributorsForVersion
and themerge
endpoints -
RelatedItemDto can be a RelatedStepDto (i.e. include workflowId
) -
is it possible to create actual query param definitions for facets? the openapi doc currently does not reflect the required params shape, see here -
wrongoperationId
s:/api/sources/{id}
#delete should be "deleteSource" not "deleteTool"/api/concept-search
#get should be "searchConcepts" not "searchItems"
-
content type "*/*"
should be"application/json"
for/api/item-search
/api/concept-search
/api/item-search/autocomplete
/api/vocabularies
/api/vocabularies/{code}
-
/api/workflows/{workflowId}/steps/{stepId}/steps
: can this get anoperationId
less similar to/api/workflows/{workflowId}/steps
(both have "createStep") -
can we extract the sort order enum (instead of inlining?) -
in item search, can we give categories
a more specific type thanRecord<string, string>
, i.e. useproperties
instead ofadditionalProperties
in openapi doc? -
similarly, can we give the items-categories
response a more specific type (currently alsoRecord<string, string>
) -
can we narrow the category
property for specific entities? e.g.DatasetDto
currently lists the full category enum as allowed values forDatasetDto.category
, when it should be narrowed todataset
. -
/api/auth/sign-in
endpoint missing -
- document required fields in POST request body / GET response payload. currently all fields are optional (openapi spec default), which does not conform to actual api behavior -
mark fields as nullable
when they allownull
(e.g.entity.source
) -
step.relatedItems
defaults tonull
instead of an empty array (as it does for other entity types) -
the requestbody schema for properties
on e.g. POST/api/datasets
says that it takes aDatasetCore
and thereforeconcept
is aConceptId
, i.e. requirescode
,vocabulary
, anduri
.uri
does not seem to actually be required. -
Resource.inputStream
is an object type without properties
thanks
edit: (2) and (4) fixed by !20 (merged)