Repository: nestjs/swagger
Pull request #650 (2020-04-02 14:14:59)

OpenAPI 3 Cookie Authentication Support
## Issue #649 

## PR Checklist
Please check if your PR fulfills the following requirements:

- [x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
- [x] Tests for the changes have been added (for bug fixes / features)
- [x] Docs have been added / updated (for bug fixes / features) https://github.com/nestjs/docs.nestjs.com/pull/1131


## PR Type
What kind of change does this PR introduce?

<!-- Please check the one that applies to this PR using "x". -->
```
[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Other... Please describe:
```

Issue Number: #649 


## What is the new behavior?
```
// main.ts
const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .addCookieAuth() // <- adds cookie authentication
    .build();

// cats.controller.ts
@ApiCookieAuth() // <- adds cookie authentication
@Controller('cats')
export class CatsController {}
```

## Does this PR introduce a breaking change?
```
[ ] Yes
[x] No
```

<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. -->


## Other information


Patch:
diff --git a/lib/decorators/api-cookie.decorator.ts b/lib/decorators/api-cookie.decorator.ts
new file mode 100644
index 00000000..13dd16df
--- /dev/null
+++ b/lib/decorators/api-cookie.decorator.ts
@@ -0,0 +1,5 @@
+import { ApiSecurity } from './api-security.decorator';
+
+export function ApiCookieAuth(name = 'cookie') {
+  return ApiSecurity(name);
+}
diff --git a/lib/document-builder.ts b/lib/document-builder.ts
index 9bb7b8b0..702b3d30 100644
--- a/lib/document-builder.ts
+++ b/lib/document-builder.ts
@@ -157,6 +157,22 @@ export class DocumentBuilder {
     return this;
   }
 
+  public addCookieAuth(
+    cookieName: string = 'connect.sid',
+    options: SecuritySchemeObject = {
+      type: 'apiKey'
+    },
+    securityName = 'cookie'
+  ): this {
+    this.addSecurity(securityName, {
+      type: 'apiKey',
+      in: 'cookie',
+      name: cookieName,
+      ...options
+    });
+    return this;
+  }
+
   public build(): Omit<OpenAPIObject, 'components' | 'paths'> {
     return this.document;
   }


Test patch:
diff --git a/e2e/api-spec.json b/e2e/api-spec.json
index 866f9eba..a53561e0 100644
--- a/e2e/api-spec.json
+++ b/e2e/api-spec.json
@@ -32,6 +32,11 @@
         "type": "apiKey",
         "in": "header",
         "name": "api_key"
+      },
+      "cookie": {
+        "type": "apiKey",
+        "in": "cookie",
+        "name": "connect.sid"
       }
     },
     "schemas": {
diff --git a/e2e/fastify.e2e-spec.ts b/e2e/fastify.e2e-spec.ts
index b182f63c..5b04022e 100644
--- a/e2e/fastify.e2e-spec.ts
+++ b/e2e/fastify.e2e-spec.ts
@@ -27,6 +27,7 @@ describe('Fastify Swagger', () => {
       .addBearerAuth()
       .addOAuth2()
       .addApiKey()
+      .addCookieAuth()
       .addSecurityRequirements('bearer');
   });
 
@@ -58,10 +59,7 @@ describe('Fastify Swagger', () => {
     await app.init();
     // otherwise throws "FastifyError [FST_ERR_DEC_ALREADY_PRESENT]: FST_ERR_DEC_ALREADY_PRESENT: The decorator 'swagger' has already been added!"
     await expect(
-      app
-        .getHttpAdapter()
-        .getInstance()
-        .ready()
+      app.getHttpAdapter().getInstance().ready()
     ).resolves.toBeDefined();
   });
 });
diff --git a/e2e/validate-schema.e2e-spec.ts b/e2e/validate-schema.e2e-spec.ts
index 7a2f7b39..1df73bc3 100644
--- a/e2e/validate-schema.e2e-spec.ts
+++ b/e2e/validate-schema.e2e-spec.ts
@@ -24,6 +24,7 @@ describe('Validate OpenAPI schema', () => {
       .addBearerAuth()
       .addOAuth2()
       .addApiKey()
+      .addCookieAuth()
       .addSecurityRequirements('bearer')
       .build();