chore: update OpenAPI script

README.md

@@ -9,10 +9,10 @@
 
 Typescript Oauth library for the [V2 Patreon API](https://docs.patreon.com/) with:
 
-- Support for Creator access tokens and Oauth tokens.
+- Support for Creator access tokens and Oauth tokens
 - Client with methods for calling every endpoint, both resource and webhook endpoints
 - Methods to create a webhook server
-- Typescript types that strongly reflect your query for raw or normalized responses.
+- Typescript types that strongly reflect your query for raw or normalized responses
 
 ```ts
 const query = buildQuery.campaign([])({ campaign: ['title']})
@@ -76,7 +76,7 @@ Tip: the Patreon API blocks browser requests, so choose a backend to handle Oaut
 
 ### OpenAPI schema
 
-This library is used to create the Patreon OpenAPI for the [`patreon-api-spec`](https://github.com/ghostrider-05/patreon-api-spec) repository. The stable spec is also available on the [API documentation](https://patreon-api.pages.dev/api/) of this library.
+This library is used to create the Patreon OpenAPI schemas for the [`patreon-api-spec`](https://github.com/ghostrider-05/patreon-api-spec) repository.
 
 ## Examples
 

docs/.vitepress/config/index.ts

@@ -44,7 +44,7 @@ export default defineConfig({
     themeConfig: {
         nav: [
             shared.createGuideItem(false),
-            { text: 'API', link: '/api/index.html', activeMatch: '/api/' },
+            { text: 'API Reference', link: 'https://patreon.apidocumentation.com/v2-stable/reference', },
             shared.createLinksItem({
                 branch,
                 bugsUrl: bugs.url,

docs/.vitepress/theme/index.ts

@@ -25,7 +25,7 @@ export default {
         DefaultTheme.enhanceApp(ctx)
         ctx.app.use(createVuetify())
 
-        const spec = await fetchOpenAPISchema('openapi-schema')
+        const spec = await fetchOpenAPISchema()
 
         // @ts-expect-error Unused variable
         // eslint-disable-next-line @typescript-eslint/no-unused-vars

docs/index.md

@@ -32,7 +32,7 @@ features:
     linkText: See runtime requirements
   - title: OpenAPI schema
     details: Use the Patreon API with popular OpenAPI tools
-    link: /api/
+    link: https://patreon.apidocumentation.com/v2-stable/reference
     linkText: Explore the API
   - title: Simplified payloads
     details: Don't want to deal with the JSON:API? Use the simplified payloads

src/schemas/v2/api/components/headers.ts

@@ -1,22 +1,27 @@
-import { PATREON_RESPONSE_HEADERS, WebhookClient } from '../../../../v2'
+import { ResponseHeaders, WebhookClient } from '../../../../v2'
 
 export default {
-    [PATREON_RESPONSE_HEADERS.UUID]: {
+    [ResponseHeaders.UUID]: {
         schema: {
             type: 'string',
         },
     },
-    [PATREON_RESPONSE_HEADERS.Sha]: {
+    [ResponseHeaders.Sha]: {
         schema: {
             type: 'string',
         },
     },
-    [PATREON_RESPONSE_HEADERS.CfCacheStatus]: {
+    [ResponseHeaders.CfCacheStatus]: {
         schema: {
             type: 'string',
         },
     },
-    [PATREON_RESPONSE_HEADERS.CfRay]: {
+    [ResponseHeaders.CfRay]: {
+        schema: {
+            type: 'string',
+        },
+    },
+    [ResponseHeaders.RetryAfter]: {
         schema: {
             type: 'string',
         },

src/schemas/v2/api/components/parameters.ts

@@ -122,7 +122,9 @@ export default {
         required: true,
         schema: {
             type: 'string',
-            default: new RestClient().userAgent,
+            examples: [
+                new RestClient().userAgent,
+            ],
         }
     },
 }

src/schemas/v2/api/paths/webhook.ts

@@ -119,6 +119,11 @@ export default [
                 id: 'editWebhook',
                 body: patchWebhookBody,
             },
+            {
+                method: RequestMethod.Delete,
+                id: 'deleteWebhook',
+                experimental: true,
+            },
         ],
         params: {
             id: 'id',

src/schemas/v2/api/types.ts

@@ -26,6 +26,7 @@ export interface Route {
         body?: Record<string, unknown>
         deprecated?: boolean
         description?: string
+        experimental?: boolean
         scopes?: PatreonOauthScope[]
         summary?: string
     }[]

src/scripts/v2/openapi/api.ts

@@ -10,6 +10,8 @@ import { PatreonOauthScope } from '../../../rest/v2'
 import { writeOpenAPISchema } from './schema'
 import { getJsDocDescription, getTypes } from '../shared'
 
+const baseAPIPath = '/api/oauth2/v2'
+
 // eslint-disable-next-line jsdoc/require-jsdoc
 function getScopes () {
     const scopeEnum = getTypes('./src/rest/v2/oauth2/scopes.ts')
@@ -27,8 +29,13 @@ function getScopes () {
 
 }
 
-// @ts-expect-error unused preview for now
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line jsdoc/require-jsdoc
+function getDocumentationUrl (route: string, method: string) {
+    return 'https://docs.patreon.com/#'
+        + method.toLowerCase()
+        + (baseAPIPath + route).replace(/\//g, '-')
+}
+
 export default (fileName: string, preview?: boolean) => writeOpenAPISchema({
     fileName,
     spacing: 2,
@@ -41,8 +48,9 @@ export default (fileName: string, preview?: boolean) => writeOpenAPISchema({
         }
     },
     paths: {
-        base: '/api/oauth/v2',
+        base: baseAPIPath,
         routes,
+        includeExperimentalRoutes: !!preview,
         formatId: (id) => `{${id ?? 'id'}}`,
         contentType: 'application/json',
         parameters: [
@@ -53,9 +61,7 @@ export default (fileName: string, preview?: boolean) => writeOpenAPISchema({
             return {
                 documentation: {
                     description: 'Official documentation',
-                    url: `https://docs.patreon.com/#${method.toLowerCase()}-api-oauth2-v2${
-                        route.route(route.params?.id ?? 'id').replace(/\//g, '-')
-                    }`,
+                    url: getDocumentationUrl(route.route(route.params?.id ?? 'id'), method),
                 },
                 responses: [
                     {

src/scripts/v2/openapi/schema.ts

@@ -9,6 +9,7 @@ interface PathSchemaOptions {
     base: string
     routes: Route[]
     contentType: string
+    includeExperimentalRoutes: boolean
     formatId: (id: string | null) => string
     parameters: (
         | string
@@ -41,7 +42,12 @@ function createPaths (schema: PathSchemaOptions) {
     return schema.routes.reduce((obj, path) => ({
         ...obj,
         [schema.base + path.route(schema.formatId(path.params?.id ?? null))]: path.methods.reduce((options, data) => {
-            const { id, method, body } = data
+            const { id, method, body, experimental } = data
+
+            if (experimental && !schema.includeExperimentalRoutes) {
+                return options
+            }
+
             const {
                 documentation: externalDocs,
                 responses: routeResponses,