Accelerate Midway Development with a Minimal Swagger Component

Minimal Swagger Component

Midway's simplest Swagger integration is now available. It is a very small, lightweight, and dependency‑free library that uses Midway's own decorator‑stored metadata, transforms it into the JSON structure recognized by Swagger, instead of the traditional AST analysis.

The benefit is that the code relies on the framework’s native capabilities, making it easy to maintain, semantically clear, and not constrained by syntax changes. Additional information can be added via other decorators.

However, this approach has limitations: it is tied to the framework and cannot be generalized, and extra content must be added through decorators rather than comments, which may require some adjustment.

Without any extra decorators, the Swagger component can correctly recognize your route, parameters, validators, DTOs, and required fields.

If you put in a bit more effort, Midway provides a set of decorators for more detailed interface descriptions, allowing the documentation to become complete.

Local Development Speedup

After a two‑week refactor, MidwayJS has prepared for the next five years. Startup speed has doubled, and users have already felt the improvement.

This version, the biggest code refactor since Midway v2, not only optimizes startup time but also supports simultaneous execution of multiple scenarios. Different upper‑level frameworks can run in the same process, and the dependency‑injection container isolates them, allowing the same code to inject different framework app instances based on runtime context.

@Provide()
export class UserService {
  @App()
  app: IMidwayApplication;

  async getUser() {
    // output this.app
  }
}

// web
@Controller()
export class UserController {
  @Inject()
  userService: UserService;
}

// socket
@WSController('/')
export class UserWSController {
  @Inject()
  userService: UserService;
}

The same UserService can be used in both web and socket scenarios; previously the injected app was the same, but now the app is bound and isolated per context.

This enables scenario‑specific handling, making the code cleaner, more reusable, and better separated.

Other Changes

Configuration Adjustments

Thanks to the refactor, the Configuration flow and trigger mechanism have been adjusted. Previously, under EggJS, Configuration triggered in both Agent and App, causing issues like duplicate database connections. Now onReady triggers only once in the Worker, aligning with typical development habits.

The loading method also changed to use the standard require approach with defined export conventions, simplifying component exports and laying groundwork for future static builds.

import { Configuration } from '@midwayjs/decorator';
import * as swagger from '@midwayjs/swagger';

@Configuration({
  imports: [
    swagger
  ]
})
export class ContainerConfiguration {

}

New Parameter Decorators

@RequestPath and @RequestIP

These new parameter decorators can be mixed with existing ones like @Body. Our Swagger component already supports them, allowing code to migrate from Koa to Express without touching the underlying framework methods.

Example: retrieve body, path, and IP

@Post('/')
async updateUser(
  @Body() id: string,
  @RequestPath() p: string,
  @RequestIP() ip: string
): Promise<User> {

}

Conclusion

Most of October was spent on this refactor. When problems arise, we are willing to invest time to fix them. Thanks to everyone who tested and gave suggestions 💖.