From 0c17cc3577350d7b9d33d226c6e9a96ec3f9b678 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Sat, 17 Aug 2024 00:15:11 +0800 Subject: [PATCH] doc: API references --- backend/src/lib/api-docs/constants.ts | 26 +++++++++++++ .../routes/v1/certificate-template-router.ts | 37 ++++++++++++------- .../certificate-templates/create.mdx | 4 ++ .../certificate-templates/delete.mdx | 4 ++ .../certificate-templates/get-by-id.mdx | 4 ++ .../certificate-templates/update.mdx | 4 ++ .../certificates/issue-certificate.mdx | 4 ++ .../certificates/sign-certificate.mdx | 4 ++ docs/mint.json | 13 ++++++- 9 files changed, 85 insertions(+), 15 deletions(-) create mode 100644 docs/api-reference/endpoints/certificate-templates/create.mdx create mode 100644 docs/api-reference/endpoints/certificate-templates/delete.mdx create mode 100644 docs/api-reference/endpoints/certificate-templates/get-by-id.mdx create mode 100644 docs/api-reference/endpoints/certificate-templates/update.mdx create mode 100644 docs/api-reference/endpoints/certificates/issue-certificate.mdx create mode 100644 docs/api-reference/endpoints/certificates/sign-certificate.mdx diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts index e2a9bbd38..e937d4047 100644 --- a/backend/src/lib/api-docs/constants.ts +++ b/backend/src/lib/api-docs/constants.ts @@ -1147,6 +1147,32 @@ export const CERTIFICATES = { } }; +export const CERTIFICATE_TEMPLATES = { + CREATE: { + caId: "The ID of the certificate authority to associate the template with", + pkiCollectionId: "The ID of the PKI collection to bind to the template", + name: "The name of the template", + commonName: "The regular expression string to use for validating common names", + subjectAlternativeName: "The regular expression string to use for validating subject alternative names", + ttl: "The max TTL for the template" + }, + GET: { + certificateTemplateId: "The ID of the certificate template to get" + }, + UPDATE: { + certificateTemplateId: "The ID of the certificate template to update", + caId: "The ID of the certificate authority to update the association with the template", + pkiCollectionId: "The ID of the PKI collection to update the binding to the template", + name: "The updated name of the template", + commonName: "The updated regular expression string for validating common names", + subjectAlternativeName: "The updated regular expression string for validating subject alternative names", + ttl: "The updated max TTL for the template" + }, + DELETE: { + certificateTemplateId: "The ID of the certificate template to delete" + } +}; + export const ALERTS = { CREATE: { projectId: "The ID of the project to create the alert in", diff --git a/backend/src/server/routes/v1/certificate-template-router.ts b/backend/src/server/routes/v1/certificate-template-router.ts index 5ca65044b..861279094 100644 --- a/backend/src/server/routes/v1/certificate-template-router.ts +++ b/backend/src/server/routes/v1/certificate-template-router.ts @@ -3,6 +3,7 @@ import { z } from "zod"; import { CertificateTemplatesSchema } from "@app/db/schemas"; import { EventType } from "@app/ee/services/audit-log/audit-log-types"; +import { CERTIFICATE_TEMPLATES } from "@app/lib/api-docs"; import { readLimit, writeLimit } from "@app/server/config/rateLimiter"; import { verifyAuth } from "@app/server/plugins/auth/verify-auth"; import { AuthMode } from "@app/services/auth/auth-type"; @@ -27,7 +28,7 @@ export const registerCertificateTemplateRouter = async (server: FastifyZodProvid }, schema: { params: z.object({ - certificateTemplateId: z.string() + certificateTemplateId: z.string().describe(CERTIFICATE_TEMPLATES.GET.certificateTemplateId) }), response: { 200: z.object({ @@ -73,12 +74,17 @@ export const registerCertificateTemplateRouter = async (server: FastifyZodProvid }, schema: { body: z.object({ - caId: z.string(), - pkiCollectionId: z.string().optional(), - name: z.string().min(1), - commonName: validateTemplateRegexField, - subjectAlternativeName: validateTemplateRegexField, - ttl: z.string().refine((val) => ms(val) > 0, "TTL must be a positive number") + caId: z.string().describe(CERTIFICATE_TEMPLATES.CREATE.caId), + pkiCollectionId: z.string().optional().describe(CERTIFICATE_TEMPLATES.CREATE.pkiCollectionId), + name: z.string().min(1).describe(CERTIFICATE_TEMPLATES.CREATE.name), + commonName: validateTemplateRegexField.describe(CERTIFICATE_TEMPLATES.CREATE.commonName), + subjectAlternativeName: validateTemplateRegexField.describe( + CERTIFICATE_TEMPLATES.CREATE.subjectAlternativeName + ), + ttl: z + .string() + .refine((val) => ms(val) > 0, "TTL must be a positive number") + .describe(CERTIFICATE_TEMPLATES.CREATE.ttl) }), response: { 200: z.object({ @@ -119,18 +125,21 @@ export const registerCertificateTemplateRouter = async (server: FastifyZodProvid }, schema: { body: z.object({ - caId: z.string().optional(), - pkiCollectionId: z.string().optional(), - name: z.string().min(1).optional(), - commonName: validateTemplateRegexField.optional(), - subjectAlternativeName: validateTemplateRegexField.optional(), + caId: z.string().optional().describe(CERTIFICATE_TEMPLATES.UPDATE.caId), + pkiCollectionId: z.string().optional().describe(CERTIFICATE_TEMPLATES.UPDATE.pkiCollectionId), + name: z.string().min(1).optional().describe(CERTIFICATE_TEMPLATES.UPDATE.name), + commonName: validateTemplateRegexField.optional().describe(CERTIFICATE_TEMPLATES.UPDATE.commonName), + subjectAlternativeName: validateTemplateRegexField + .optional() + .describe(CERTIFICATE_TEMPLATES.UPDATE.subjectAlternativeName), ttl: z .string() .refine((val) => ms(val) > 0, "TTL must be a positive number") .optional() + .describe(CERTIFICATE_TEMPLATES.UPDATE.ttl) }), params: z.object({ - certificateTemplateId: z.string() + certificateTemplateId: z.string().describe(CERTIFICATE_TEMPLATES.UPDATE.certificateTemplateId) }), response: { 200: z.object({ @@ -172,7 +181,7 @@ export const registerCertificateTemplateRouter = async (server: FastifyZodProvid }, schema: { params: z.object({ - certificateTemplateId: z.string() + certificateTemplateId: z.string().describe(CERTIFICATE_TEMPLATES.DELETE.certificateTemplateId) }), response: { 200: z.object({ diff --git a/docs/api-reference/endpoints/certificate-templates/create.mdx b/docs/api-reference/endpoints/certificate-templates/create.mdx new file mode 100644 index 000000000..56fcf3791 --- /dev/null +++ b/docs/api-reference/endpoints/certificate-templates/create.mdx @@ -0,0 +1,4 @@ +--- +title: "Create" +openapi: "POST /api/v1/pki/certificate-templates" +--- diff --git a/docs/api-reference/endpoints/certificate-templates/delete.mdx b/docs/api-reference/endpoints/certificate-templates/delete.mdx new file mode 100644 index 000000000..c4f13d470 --- /dev/null +++ b/docs/api-reference/endpoints/certificate-templates/delete.mdx @@ -0,0 +1,4 @@ +--- +title: "Delete" +openapi: "DELETE /api/v1/pki/certificate-templates/{certificateTemplateId}" +--- diff --git a/docs/api-reference/endpoints/certificate-templates/get-by-id.mdx b/docs/api-reference/endpoints/certificate-templates/get-by-id.mdx new file mode 100644 index 000000000..802dc5326 --- /dev/null +++ b/docs/api-reference/endpoints/certificate-templates/get-by-id.mdx @@ -0,0 +1,4 @@ +--- +title: "Get by ID" +openapi: "GET /api/v1/pki/certificate-templates/{certificateTemplateId}" +--- diff --git a/docs/api-reference/endpoints/certificate-templates/update.mdx b/docs/api-reference/endpoints/certificate-templates/update.mdx new file mode 100644 index 000000000..53c5f6fdf --- /dev/null +++ b/docs/api-reference/endpoints/certificate-templates/update.mdx @@ -0,0 +1,4 @@ +--- +title: "Update" +openapi: "PATCH /api/v1/pki/certificate-templates/{certificateTemplateId}" +--- diff --git a/docs/api-reference/endpoints/certificates/issue-certificate.mdx b/docs/api-reference/endpoints/certificates/issue-certificate.mdx new file mode 100644 index 000000000..90a79a4af --- /dev/null +++ b/docs/api-reference/endpoints/certificates/issue-certificate.mdx @@ -0,0 +1,4 @@ +--- +title: "Issue Certificate" +openapi: "POST /api/v1/pki/certificates/issue-certificate" +--- diff --git a/docs/api-reference/endpoints/certificates/sign-certificate.mdx b/docs/api-reference/endpoints/certificates/sign-certificate.mdx new file mode 100644 index 000000000..3132d5846 --- /dev/null +++ b/docs/api-reference/endpoints/certificates/sign-certificate.mdx @@ -0,0 +1,4 @@ +--- +title: "Sign Certificate" +openapi: "POST /api/v1/pki/certificates/sign-certificate" +--- diff --git a/docs/mint.json b/docs/mint.json index ac61ad5bd..98d6f01ac 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -686,7 +686,18 @@ "api-reference/endpoints/certificates/read", "api-reference/endpoints/certificates/revoke", "api-reference/endpoints/certificates/delete", - "api-reference/endpoints/certificates/cert-body" + "api-reference/endpoints/certificates/cert-body", + "api-reference/endpoints/certificates/issue-certificate", + "api-reference/endpoints/certificates/sign-certificate" + ] + }, + { + "group": "Certificate Templates", + "pages": [ + "api-reference/endpoints/certificate-templates/create", + "api-reference/endpoints/certificate-templates/update", + "api-reference/endpoints/certificate-templates/get-by-id", + "api-reference/endpoints/certificate-templates/delete" ] }, {