Hosted store OAS is incorrect for Medusa V1

[dwene]

What Medusa version and documentation are you using?

v1

Preliminary Checks

• [X] This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/medusajs/medusa/issues

Issue Summary

TLDR: The storefront openapi.yaml file hosted here: https://docs.medusajs.com/api/download/store?version=1 used by medusa-oas-cli is incorrect and needs to be regenerated and hosted by running medusa-oas oas --type=store --local and hosting the result.

The long answer:

I'm trying to use the medusa medusa-oas cli to generate a medusa storefront http client. In this past this has worked great, but I noticed when trying to generate my storefront client that it's not working. It's having a hard time generating types.

Digging into the error, I found that the openapi.yaml that is generated is incorrect. Typically that's a me problem so I looked. Even removing all my custom @schema and @oas comments in my code it still failed.

Digging into the code, I found that the medusa-oas cli uses a hosted version of the oas file to start, then modifies that based on comments in code.

The URL it's using is: https://docs.medusajs.com/api/download/store?version=1

I noticed that there's some errors in there that cause the types generation to fail when trying to run:

For example, in components/schemas/Customer:

        orders:
          description: The details of the orders this customer placed.
          type: array
          x-expandable: orders
          items:
            type: object

items has type: object instead of what it should be $ref: '#/components/schemas/Order'

medusa-oas has a way to regenerate the base file if you are in the medusa monorepo by passing --local. I did that and the generated oas file is correct as I would expect.

Typically I wouldn't bother y'all with this since you are working so hard on v2. But since it's hardcoded in the medusa-oas package to start with the file hosted at "https://docs.medusajs.com/api/download/store?version=1" , I need to run patch-package everywhere I use this.

Can we please update the file with the correct openapi schema file?

How can this issue be resolved?

1. Open the medusa monorepo with branch "v1.x"
2. run yarn medusa-oas oas --type=store --local
3. copy the file and upload it to wherever https://docs.medusajs.com/api/download/store?version=1 pulls from. I would happily do it, but I don't think I can... :/

If you trust me, I've generated it here already (github won't let me upload a yaml so I had to zip the file): oas.zip

Thanks!

Are you interested in working on this issue?

• [X] I would like to fix this issue

[sradevski]

@shahednasser I don't have much context on this one, can you have a look?

[shahednasser]

Hi @dwene , thank you for opening this issue!

I noticed that there's some errors in there that cause the types generation to fail

Can you provide more details on what's failing exactly? Is there an error message that you can share?

items has type: object instead of what it should be $ref: '#/components/schemas/Order'

This is changed by our tools to remove circular references when generating the openapi.yaml file. So, re-generating the OAS in the v1.x branch won't change anything.

For the record, we use the openapi:generate command in the monorepo, which runs medusa-oas oas --type=store --local and medusa-oas oas --type=admin --local to generate the files hosted in the API reference.

medusa-oas has a way to regenerate the base file if you are in the medusa monorepo by passing --local. I did that and the generated oas file is correct as I would expect.

Again, need more details on this. Running yarn medusa-oas oas --type=store --local in the monorepo root only generates a file at packages/oas/medusa-oas-cli/store.oas.json. However, you mention:

copy the file and upload it to wherever https://docs.medusajs.com/api/download/store?version=1 pulls from

We don't commit json files and the generated file that you download is yaml.

Again, if you can provide more details on the error you're facing with generating types that would be great, maybe the solution is different than what you think.

[github-actions[bot]]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 3 days.

[github-actions[bot]]

This issue was closed because it has been stalled for 3 days with no activity.