acacode / acacode/swagger-typescript-api

Addressing Naming Conflicts in Swagger-Generated TypeScript API

Open
#657 0 comments 3 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4.1k
Forks
436
PR merge metrics
No merged PRs in 30d

Description

**Introduction:**
Hello guys, we come form **Ardextechnology**
We are currently utilizing Swagger-Typescript-API version 13.0.0 within our project.
We have encountered an issue related to method naming that we aim to resolve.

**The Issue:**
The problem arises when dealing with API routes that involve path parameters. For example, consider the following API routes:

**GetAllBookByCategoryId:**
**GET: /api/categories/{categoryId}/books GetAllBookByCategoryId**
**GetBookById:**
**GET: /api/categories/{categoryId}/books/{bookId}**

When running the generated API, we encountered a naming conflict within our codebase. Specifically, we have received the following error message:

"Module 'xxx' already has the method '**categoriesBooksDetail()**'. This method has been renamed to '**categoriesBooksDetail2()**' to resolve naming conflicts."

**Observations:**
Upon closer examination, we have noticed that the Swagger TypeScript API tool consistently appends a "Detail" suffix to the method name when the URL contains a path parameter (e.g., {categoryId}). However, when no path parameters are present in the route, the tool generates a method with a 'List' suffix, indicating its intent to retrieve a list of items, and there is no path parameter in the route's suffix.

**Our Concern:**
We believe that this consistent "Detail" naming convention is leading to method naming conflicts. It is causing confusion and making it challenging to differentiate between different routes, especially when the "Detail" suffix is appended even when it may not be appropriate.

**Proposed Solution:**
Our suggested solution is to check whether a URL segment contains a path parameter at the end or not. Based on this check, we can create a suitable method name.

**Suggested Code Implementation:**
In the **route-name.ejs** file
**const hasPathDetails = /\{[^/]+\}$/.test(route);**

**const methodName = _.camelCase(`${pathName}_${hasPathDetails ? "detail" : "list"}`);**

We believe that this solution can assist in generating method names that align more intuitively with the actual route structure, thus reducing naming conflicts.

We greatly appreciate your attention to this matter and welcome any insights or suggestions from the community. Together, we can enhance the naming convention in our TypeScript API and avoid unnecessary conflicts.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.