feat: add order to force ordering for paths

Author: maxholman

lib/operation.ts

@@ -7,6 +7,7 @@ import type { Response } from './response.js';
 import type { SecurityRequirement } from './security-requirement.js';
 import type { Tag } from './tag.js';
 import type { ExtractRouteParams } from './types.js';
+import { stripUndefined } from './utils.js';
 
 export interface OperationOptions<TPath extends string = '/'> {
   operationId: string;
@@ -20,13 +21,16 @@ export interface OperationOptions<TPath extends string = '/'> {
     [statusCode: string | number]: Response;
   };
   requestBody?: RequestBody | RequestBodyOptions;
+  order?: number;
 }
 
 export class Operation<TPath extends string = '/'> extends Construct {
   private readonly options: OperationOptions<TPath>;
 
   public readonly method: HttpMethods;
 
+  public readonly order: number;
+
   private requestBody?: RequestBody;
 
   public hasOperationId(operationId: OperationOptions['operationId']): boolean {
@@ -42,6 +46,8 @@ export class Operation<TPath extends string = '/'> extends Construct {
     this.method = method;
     this.options = options;
 
+    this.order = options.order || 0;
+
     if (options.requestBody) {
       this.requestBody =
         options.requestBody instanceof RequestBody
@@ -68,10 +74,13 @@ export class Operation<TPath extends string = '/'> extends Construct {
   }
 
   public synth() {
-    return {
-      ...(this.options.operationId && {
-        operationId: this.options.operationId,
-      }),
+    return stripUndefined({
+      operationId: this.options.operationId,
+      description: this.options.description || undefined,
+      summary: this.options.summary || undefined,
+      tags:
+        this.options.tags && [...this.options.tags].map((child) => child.name),
+      deprecated: this.options.deprecated,
       ...(this.options.parameters && {
         parameters: this.options.parameters.map((child) => child.synth()),
       }),
@@ -92,6 +101,6 @@ export class Operation<TPath extends string = '/'> extends Construct {
           ]),
         ),
       }),
-    } satisfies oas31.OperationObject;
+    }) satisfies oas31.OperationObject;
   }
 }

lib/path.ts

@@ -1,4 +1,3 @@
-import { strict } from 'node:assert';
 import { Construct } from 'constructs';
 import type { oas31 } from 'openapi3-ts';
 import type { Api } from './api.js';
@@ -30,7 +29,7 @@ export class Path<TPath extends string = '/'> extends Construct {
     options: OperationOptions<TPath>,
   ): this {
     // make sure we are not duplicating tags
-    options.tags?.forEach((tag) => strict(!this.options.tags?.has(tag)));
+    // options.tags?.forEach((tag) => strict(!this.options.tags?.has(tag)));
 
     // eslint-disable-next-line no-new
     new Operation(this, method, {
@@ -52,6 +51,7 @@ export class Path<TPath extends string = '/'> extends Construct {
           .filter(
             (child): child is Operation<TPath> => child instanceof Operation,
           )
+          .sort((a, b) => a.order - b.order)
           .map((child) => [child.method, child.synth()]),
       ),
       ...(this.options.servers && {