SkeLLLa/fastify-oas

How to use this plugin?

Closed this issue · 9 comments

tanvp112 commented

Hi,

Need help to understand what does it means by "Unlike regular OpenAPI spec you'll still need some options from swagger 2.0" from https://github.com/SkeLLLa/fastify-oas#openapi

What is this "some options" to be precise?

I have difficulty using this plug-in at the moment... browsing to base_url/documentation return 404. Appreciate if it is possible, please upload an example illustrating how petstore in openapi version 3.0 can be serve from fastify-oas? Understood that this plugin only show the document (ReDoc?) and will not implement the spec.

Thanks.

tanvp112 commented

Does the statement means to generate 3.0 doc, there is need to use swagger 2.0 keywords? Using your example, the swagger 2.0 key 'consumes' was specified despite the example was expected to generate 3.0 spec.

Can i set the 'swagger' object by copy a openapi 3.0 spec to it?

Thanks.

SkeLLLa commented

Does the statement means to generate 3.0 doc, there is need to use swagger 2.0 keywords?

Short answer - yes. Long answer: swagger object contains fields that are related to this plugin. It's not a place for storing your swagger or openapi spec.

Can i set the 'swagger' object by copy a openapi 3.0 spec to it?

That depends on what you have in your openapi spec. You can try, but there's no guarantee that it will work as you expect. Consider swagger object as something that related to this plugin options only, not swagger or openapi.

olafkrueger commented

browsing to base_url/documentation return 404

Did you ensure to set exposeRoute: true as shown in the (updated) usage example?

Does the statement means to generate 3.0 doc

You can output the generated docs by calling e.g.
console.log( fastify.oas() )

Maybe it helps to investigate the generated docs in order to understand what's going on...

I am not yet a Fastify expert but maybe this helps a bit ;-)

SkeLLLa commented

Did you ensure to set exposeRoute: true as shown in the (updated) usage example?

How to use exposeRoute is described in readme. By default it false, so it's ok if you receive 404. It's done like that in order to be compatible with fastify-swagger plugin.

olafkrueger commented

You can output the generated docs by calling e.g.
console.log( fastify.oas() )

I was maybe a little too hasty, calling fastify.oas() within my test installation outputs something like this where e.g. [Objects] aren't resolved.

{
  openapi: '3.0.0',
  info: {
    title: 'ebase API',
    description: 'testing the fastify swagger api',
    version: '0.1.0'
  },
  components: {},
  externalDocs: { url: 'https://swagger.io', description: 'Find more info here' },
  servers: [ { url: 'http://127.0.0.1/' } ],
  paths: {
    '/auth': { post: [Object] },
    '/example': { get: [Object] },
    '/root': { get: [Object] }
  }
}

Do I miss something or is there any other option to output the generated docs which is finally used by Swagger-UI?

Thanks!

SkeLLLa commented

@olafkrueger fastify.oas() returns an object that swagger ui uses later. So it's ok to call it.
Why do you think that "[Objects]" aren't resolved? Have you tried to JSON.stringify(fastify.oas()) see full output?

olafkrueger commented

Have you tried to JSON.stringify(fastify.oas()) see full output?

Ohhh yes, of course!
That question was really just plain stupid by me, sorry for annyoing you ;-)

I guess I was a bit distracted because I missed a defined route in the output object and I therefore I thought something was wrong with the output. But it turns out that I had an an issue on my side.

However, thanks!

  • 👍1
tanvp112 commented

Does the statement means to generate 3.0 doc, there is need to use swagger 2.0 keywords?

Short answer - yes. Long answer: swagger object contains fields that are related to this plugin. It's not a place for storing your swagger or openapi spec.

Can i set the 'swagger' object by copy a openapi 3.0 spec to it?

That depends on what you have in your openapi spec. You can try, but there's no guarantee that it will work as you expect. Consider swagger object as something that related to this plugin options only, not swagger or openapi.

so the swagger here is NOT related to actual swagger/openapi standard but the plugin itself, yet actual swagger keywords are used and it is not bound to v2 or v3 standard.

thanks.