[idea] support openapi/swagger

[OleksandrKucherenko]

Two use cases:

• generate mappersmith forge code from openapi definition
• and reverse operation: generate openapi/swagger definition from mappersmith forged interface

[klippx]

Interesting idea, seems useful. Lets take https://petstore.swagger.io/ as an example, trying to "auto generate" this by hand:

forge({
  host: 'https://petstore.swagger.io/v2',
  resources: {
    Pet: {
      uploadImage: {
        method: 'post',
        path: '/pet/{petId}/uploadImage',
      },
      // No good name can be auto generated, relying on PUT = update
      update: {
        method: 'put',
        path: '/pet',
      },
      // No good name can be auto generated, relying on POST = create
      create: {
        method: 'post',
        path: '/pet',
      },
      findByStatus: {
        method: 'get',
        // Hard to express the required query parameters,
        // it would be better to hand roll it and require the user to provide the query parameters
        // path: '/pet/findByStatus/{status}',
        // even though that does not map to the actual API that we are auto-generating for
        path: '/pet/findByStatus',
      },
      // Probably need to suffix with "ByPetId" to distinguish it from potential GET /pet (if it existed)
      // Relying on GET = get, adding a (By + {petId}) camelized to separate it from vanilla "get" as mentioned above
      getByPetId: {
        method: 'get',
        path: '/pet/{petId}',
      },
      // This is another POST request, but it's not a good name.
      // Need to distinguish it from the other POST request "create".
      // But it looks strange to use Pet.createById vs Pet.create, and to add salt to injury
            // the swagger docs call this request "update pet" even though it is a post request, should have been a PUT
      createByPetId: {
        method: 'post',
        path: '/pet/{petId}',
      },
      // Similarly
      deleteByPetId: {
        method: 'delete',
        path: '/pet/{petId}',
      },
    },
    Store: {
      createOrder: {
        method: 'post',
        path: '/store/order',
      },
      getOrderByOrderId: {
        method: 'get',
        path: '/store/order/{orderId}',
      },
      deleteOrderByOrderId: {
        method: 'delete',
        path: '/store/order/{orderId}',
      },
      getStoreInventory: {
        method: 'get',
        path: '/store/inventory',
      },
    },
  },
});

First of all:

• Mappersmith would probably want to group into two primary resources Pet and Store.
• Then we want to have useful names to describe what the resourceMethod is doing, but this also need to be generated, which is the big immediate challenge

I spotted a number of things, like:

• trying to rely on "POST = create" (even though in this example it can apparently be "POST = update")
• many resources are competing for similar names (POST /pet vs POST /pet/{petId}) that need to generate code that does not clash and correctly represent the operation
• dependent on swagger docs to name their vars and camelize from that

If someone wants to do this I would say two things

• don't bring in any dependencies
• if you have to bring in dependencies, consider making this an npx command (and a separate project)

[OleksandrKucherenko]

Can it be a sub-package of the mappersmith? Maybe introduce some namespace for it?

https://github.com/OpenAPITools/openapi-generator solves the problem of naming. Maybe not in the most efficient way, and anyway its a subject of change after first iteration.

[OleksandrKucherenko]

There are many generator available - https://openapi-generator.tech/docs/generators

So I assume we can simply provide own generator for openapi-generator tool that uses Mappersmith

[OleksandrKucherenko]

Examples of generators:

• https://openapi-generator.tech/docs/generators/typescript-axios/
• https://openapi-generator.tech/docs/generators/typescript-fetch/
• https://openapi-generator.tech/docs/generators/protobuf-schema/

That may give extra power to the mappersmith

[klippx]

Very very interesting. Thanks for sharing! I have to say that I noticed that someone outside of Axios (with no contribution or affiliation with them) added the generator for typescript-axios. Lucky them, I guess.

If I understand correctly then we can achieve this with a PR to the repo:

• https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources

If anyone want to work on this, go for it.

Do you think we can close this for now, and open a new issue if there is an action to be done in this repo?