### What
Declare `x-codegen` in OAS for Admin routes - A to D.
### Why
We are introducing a new `x-codegen` OpenApi extension, also known as _vendor extension_, in order to help with passing information down to code generators.
In our case, we wish to declare the `method` name that we would expect to call on a client. This mimics our current JS client package.
E.g. `medusaClient.product.list` where `product` is the tag of the route and `list` is the x-codegen.method value.
We are also defining the name of a potential typed object for query parameters. OAS 3.0 does not allow to bundle query parameters under a single definition but it is not uncommon to see API clients handle all query parameters as a single typed object, like our JS client package. With x-codegen.queryParams, a code generator can create a named and typed object to bundle all query parameters for a given route.
E.g. `medusaClient.customer.retrieve(id: string, queryParams: AdminGetCustomerParams)`
### How
Declare `x-codegen` as an object with fields `method` and `queryParams` on all paths.
Match method and queryParams values with equivalent ones from our current JS client package.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect no visible changes to the documentation.
### What
Move inline OAS requestBody schema declaration under their respective class-validator classes in order to expose them through `#/components/schemas`. Replace inline OAS requestBody schema with a `$ref` reference pointing to the newly declared schema.
### Why
Having requestBody declared as its own "named" schema will allow OAS code generators to output typed entities/DTO that can be manipulate without having to reference the route/operation.
### How
Declare a new @schema JSDoc for each class-validator used to parse and validate request body. Move the current inline requestBody to the new @schema.
### Test
- Ran OAS validator.
- Ran docs build script.
Expect no visible changes to the documentation.
### Out-of-scope
requestBody of type `multipart/form-data` used for file uploads. These will be address as part of CORE-934
- [create-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-upload.ts#L87-L90)
- [create-protected-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts#L87-L90)
Path Parameter and Query Parameter. These will need more research and experimentation, part of CORE-931
---
Resolves CORE-853
### What
Rename all JSDoc OAS `@schema` and `$ref: #/components/schemas/` from snake_case to PascalCase, `foo_bar -> FooBar`
Extra scope: Remove `x-resourceId` from JSDoc OAS.
### Why
Classes use PascalCase as a convention but the OAS @schemas describing them were using snake_case. OAS code generators tend to use the schema name when generating typed models.
In order to avoid mismatch between source code, the OAS, and the generated client code, it is advised to align OAS @schemas formatting to the classes they represent.
Extra scope: x-resourceId is not a widely used OAS property. It's current usage in our OAS does not provide additional value. Therefore, we recommend to remove it in order to have one less item to maintain.
### How
Good old search & replace. Regex search to further make sure we didn't miss any.
The scope is limited to `@schema` definition and their usage in `$ref: #/components/schemas/`.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect no visible changes to the documentation.
Resolves: CORE-852, CORE-859
### What
OAS: Explicitly declare type:object on schemas with properties.
### Why
While not officially required, schemas with properties should have their type explicitly declared as "object". Omitting the type translates to type: any with properties XYZ. The ambiguity can lead to issues when using code generators.
### How
Multiple regex searches to identify schemas missing type: object. Manually edit each schema. Spot check generated OAS.
### Testing
- Ran OAS validator.
- Ran docs build script
### Proof
RESOLVES CORE-847
* change titles for admin apis
* adjusted titles for storefront apis
* added a note about length in contribution guidelines
* adjusted title for get customer endpoint
Patrick
Philip Korsholm
Carlos R. L. Rodrigues
Shahed Nasser
Adrien de Peretti
Oliver Windall Juhl
