express-openapi: Unclear how to validate successful completion of tutorial

[prescod]

The express-openapi tutorial is excellent until the last paragraph. At the end, it seems to rely on other knowledge which a beginner might not have.

open-api/packages/express-openapi/README.md

Line 289 in f5eb28e

Our paths are now active and we can test them out with [Swagger UI](http://petstore.swagger.io/). This getting started guide

"Our paths are now active and we can test them out with Swagger UI. "

How do we test them? How does one invoke the Swagger UI? What does this have to do with the Petstore?

Those were the questions I had (and have) after finishing the tutorial.

I would have liked to have had a couple of localhost URLs I could probe to see it working.

=====

What I see on http://localhost:8000/v1/api-docs

is:

  "paths":{}

Is that correct?

Is this URL supposed to work?

http://localhost:8000/v1/worlds/getWorld?name=earth

It doesn't. Admittedly I made some changes to the whole thing, because I was trying to use TypeScript instead of JavaScript.

[JamesBewley]

I'm trying to get started with this library but struggled to find a complete working example.

I suppose I've learned a bit along the way but having complete runable examples would have cut a lot of time.

The URL you are after is:

http://localhost:3000/v1/worlds?worldName=Earth

[JamesBewley]

I've got it hald working inside an existing app but post appear to never hit my method and ends up in the node final handler.

Is there anyway to up the debug from openAPI?

[sbland]

@prescod or @JamesBewley can you show an example of your express file that lets you get a response from one of those urls? Did you change api-v1 to v1?

[JamesBewley]

The example on the README should work without changes, it's the 'basePath' that sets which url the API is bound to. In the example it is set to basePath: '/v1'

[sbland]

Great thanks. Would be good to add the http://localhost:3000/v1/worlds?worldName=Earth url to the docs. I also got tripped up by trying http://localhost:3000/v1/worlds which returns a not very descriptive 400 error.