osv.dev
osv.dev copied to clipboard
google
Fix API documentation
The current API documentation indicates that when specifying packages, the purl field is optional, but the ecosystem and package name is required.
This is incorrect, the actual (and intended) implementation is to have to pass in either both ecosystem and package name, OR the purl field.
Related: https://github.com/google/osv.dev/issues/466
Our API generation is pretty hacky in general (auto-generated form a swagger definition which is in turn autogenerated from our protobuf definitions).
It might make sense to figure out something better (and more well integrated into our main https://osv.dev site).
We don't have that many API methods in the first place either -- maybe it's not so bad to make this more manually written instead too rather than autogenerated.
Already we have a ton of hacks in https://github.com/google/osv.dev/blob/master/docs/build.py to make the autogenerated docs contain what we want.
Another thing to clarify as part of this overhaul: https://github.com/google/osv.dev/issues/573
querybatch returns non-hydrated results.
I'd be happy to give a hand with this, or with replacing the Swagger (OpenAPI 2.0) with an OpenAPI 3.x document.
I've found that validating the generated spec (via):
echo 'extends: ["spectral:oas"]' > .spectral.yml
npx @stoplight/spectral lint osv_service_v1.swagger.json
Returns:
osv_service_v1.swagger.json
1:1 warning oas2-api-schemes OpenAPI host "schemes" must be present and non-empty array.
3:10 warning info-contact Info object must have "contact" object. info
16:14 warning operation-description Operation "description" must be present and non-empty string. paths./v1/query.post
55:14 warning operation-description Operation "description" must be present and non-empty string. paths./v1/querybatch.post
94:13 warning operation-description Operation "description" must be present and non-empty string. paths./v1/vulns/{id}.get
137:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvAffected.properties.package.description
221:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvRange.properties.type.description
253:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvReference.properties.type.description
280:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvSeverity.properties.type.description
392:25 warning oas2-unused-definition Potentially unused definition has been detected. definitions.protobufNullValue
✖ 10 problems (4 errors, 6 warnings, 0 infos, 0 hints)
Which can lead to some OpenAPI client generators fail to operate 🤔
I'd be happy to give a hand with this, or with replacing the Swagger (OpenAPI 2.0) with an OpenAPI 3.x document.
I've found that validating the generated spec (via):
echo 'extends: ["spectral:oas"]' > .spectral.yml npx @stoplight/spectral lint osv_service_v1.swagger.jsonReturns:
osv_service_v1.swagger.json 1:1 warning oas2-api-schemes OpenAPI host "schemes" must be present and non-empty array. 3:10 warning info-contact Info object must have "contact" object. info 16:14 warning operation-description Operation "description" must be present and non-empty string. paths./v1/query.post 55:14 warning operation-description Operation "description" must be present and non-empty string. paths./v1/querybatch.post 94:13 warning operation-description Operation "description" must be present and non-empty string. paths./v1/vulns/{id}.get 137:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvAffected.properties.package.description 221:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvRange.properties.type.description 253:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvReference.properties.type.description 280:26 error no-$ref-siblings $ref must not be placed next to any other properties definitions.osvSeverity.properties.type.description 392:25 warning oas2-unused-definition Potentially unused definition has been detected. definitions.protobufNullValue ✖ 10 problems (4 errors, 6 warnings, 0 infos, 0 hints)Which can lead to some OpenAPI client generators fail to operate 🤔
Hey, thanks for the offer @jamietanna ! We would love help with fixing up the openapi document that we have. We were previously mostly just using this as a way to auto-generate docs, but it would be great to make this more useful to other consumers.