redocly: no-unresolved-refs

nadilas commented 2 years ago

Hey @ecyrbe,

I wanted to upload the exported api definition which we generate here https://github.com/dotindustries/bouncer/blob/8d9831a6ac5ace6cde099e751741c1f15b5ecf19/packages/core/src/common/api.ts#L59 to Redocly, but the linter caught a few issues.

no-unresolved-refs:

spec.yaml#/paths/~1subscriptions~1{subscriptionId}~1seats~1{seatId}/get/responses/200/content/application~1json/schema/properties/created_utc
Error was generated by the no-unresolved-refs rule.

operation-summary:

spec.yaml#/paths/~1subscriptions~1{subscriptionId}~1seats/get/summary
Warning was generated by the operation-summary rule.

security-defined:

spec.yaml#/paths/~1publisher~1{publisherId}~1configuration/get
Warning was generated by the security-defined rule.

✅ solved by adding the securityScheme option to the toOpenApi call.

Any suggestions on how to address the first two?

ecyrbe commented 2 years ago

Can you share the generated yaml ?

nadilas commented 2 years ago

Can't access directly, but swagger editor shows the same issues.

https://gist.github.com/nadilas/db1690d5caad0d96f3dc4c0a28ffae99

If you want to test locally, this is the command redocly runs:

npx @redocly/cli@latest lint spec.yaml --extends minimal --format json --lint-config=off

ecyrbe commented 2 years ago

Hello, this issue will need some Time to be fixed. I have no workaround for the moment.

ecyrbe commented 2 years ago

@nadilas hello, the first issue should be fixed on @zodios/openapi v10.4.6 use it in coordination with last version @zodios/core v10.5.2

nadilas commented 2 years ago

Hi @ecyrbe, awesome, confirmed: All refs are validated in the output. You want to keep this open for the summary topic?

ecyrbe commented 2 years ago

yes you can.

ecyrbe commented 2 years ago

@nadilas So for the second error, it's just that you did not provided a description to the API, zodios support it out of the box: here is an example :

const api = makeApi([
  {
     method: 'get',
     path: '/resource',
     description: 'endpoint to get a resource', //< add a description
     response: yourschema
  }
]);

And also, you can now use the openapi builder, this way, you don't need to merge the apis, see the docs Also to check all the descriptions you can add, check here

ecyrbe / zodios-openapi

redocly: no-unresolved-refs #44