feat: Generate MyAccount API assets by agiannelli-auth0 · Pull Request #650 · auth0/docs-v2

agiannelli-auth0 · 2026-02-19T20:51:40Z

Description

This PR begins the process of implementing MyAccount API in Mintlify.

Changes:

Updated script to:
- add code snippets to myaccount-oas leveraging @fern-api/auth0-myaccount-snippets
- more accurately generate mdx files & tree in docs.json
- properly register openapi spec
First run of the script to generate MyAccount API pages

References

https://auth0team.atlassian.net/browse/DM-289

Testing

Video of local MyAccount API running

Screen.Recording.2026-02-20.at.2.15.27.PM.mov

Video of MyAccount API proxied through docs-backend with docs_explorer_mintlify_myaccount_enabled FF on and off. Flag is initially off and you see the v1 experience. With the flag on, you see the v2 experience
NOTE: This video was take prior to some additional work on the MyAccount pages themselves. Reference video above for latest look & feel.

Screen.Recording.2026-02-19.at.4.34.28.PM.mov

Checklist

I've read and followed CONTRIBUTING.md.
I've tested the site build for this change locally.
I've made appropriate docs updates for any code or config changes.
I've coordinated with the Product Docs and/or Docs Management team about non-trivial changes.

...count/authentication-methods/confirm-the-enrollment-of-a-supported-authentication-method.mdx

scripts/artifact-generation.js

nlucero · 2026-02-20T14:20:47Z

⚠️ I noticed the following errors in the console, though the pages load up fine.

These are probably SSR errors. Did you check the browser console when rendering these pages? Did you see any similar errors?

… not

agiannelli-auth0 · 2026-02-20T18:02:22Z

⚠️ I noticed the following errors in the console, though the pages load up fine.

These are probably SSR errors. Did you check the browser console when rendering these pages? Did you see any similar errors?

I see this error in the browser console:

Error: A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received

This is likely something internal to Mintlify that I will need to ask them about.

agiannelli-auth0 · 2026-02-20T18:18:53Z

@nlucero I don't know that the console errors are related to this, but I am still trying to identify a root cause and see if I can address.

agiannelli-auth0 · 2026-02-20T19:34:49Z

@nlucero I don't know that the console errors are related to this, but I am still trying to identify a root cause and see if I can address.

This issue is fixed.

nlucero · 2026-02-23T14:33:24Z

scripts/artifact-generation.js

  const mdxContent = dedent`
    ---
-    openapi: ${file} ${method} ${path}
+    openapi: ${method} ${path}


Question: This doesn't seem right. According to their docs:

If you have multiple OpenAPI specifications, include the file path in your reference.

Since we will eventually have multiple OASs, shouldn't we be explicit here and set the file property as well?

I don't believe this is an issue when you declare the OAS files in docs.json (ref)

Locally I added a second My Account API + a sample Petstore API, generated the files, and things worked as expected.

Will this also work with different localized versions of the same schema? E.g. when viewing a MyAccount endpoint page in fr-ca, it should read from main/docs/oas/myaccount/myaccount-api-oas.fr-ca.json.

✋🏽 Change Request: Please revert this change. The openapi property needs three values for the scenario we are creating for ourselves. We need file, method, and path

(see prev comment - ref)

nlucero · 2026-02-23T14:40:20Z

scripts/artifact-generation.js

  return docsJson;
 }

+async function getOasFilePath({ locale, oasConfig }) {


Question: Where are we using this function? I only see it imported in tests 🤔

Good catch! This was a miss on my part when I was testing the English fallback 🙈 . This has been reimplemented!

nlucero · 2026-02-24T16:15:13Z

scripts/artifact-generation.js

+  if (locale === "en") {
+    return enPath;
+  }
+  const localeFilename = chain(oasConfig.outputFile)


Nit: Add a code comment above this line with a little example of what this does, it should help when reading it.

mikemimik · 2026-02-24T18:20:55Z

...count/authentication-methods/confirm-the-enrollment-of-a-supported-authentication-method.mdx

@@ -0,0 +1,9 @@
+---
+openapi: post /authentication-methods/{authentication_method_id}/verify


✋🏽 Change Request: The openapi property should have three values: file, method, path. We'll need to update the generation script to add these.

mikemimik · 2026-02-24T18:21:19Z

package.json

  "homepage": "https://github.com/auth0/docs-v2#readme",
  "dependencies": {
    "@a0/myaccount-api-oas": "1.404.0",
+    "@fern-api/auth0-myaccount-snippets": "^0.0.2",


✋🏽 Change Request: can you please pin this dependency

mikemimik · 2026-02-24T18:22:53Z

scripts/artifact-generation.js

    ---

-    import { ReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
+    import { ReleaseLifecycle } from "/snippets/ReleaseLifecycle.jsx";


✋🏽 Change Request: The snippet should be called ApiReleaseLifecycle. Can we update the name of the file instead of changing the name here please.

mikemimik · 2026-02-24T18:24:28Z

scripts/artifact-generation.js

  const mdxContent = dedent`
    ---
-    openapi: ${file} ${method} ${path}
+    openapi: ${method} ${path}


✋🏽 Change Request: Please revert this change. The openapi property needs three values for the scenario we are creating for ourselves. We need file, method, and path

(see prev comment - ref)

mikemimik · 2026-02-24T18:57:16Z

scripts/artifact-generation.js

+  const indexContent = dedent`
+    ---
+    title: "${apiName}"
+    description: "${apiName} endpoints"


✋🏽 Change Request: there shouldn't be untranslated text in these templates. This value can just be passed in.

mikemimik · 2026-02-24T18:58:51Z

scripts/artifact-generation.js

+ * Note: This file will be ignored if it already exists to prevent
+ * loss of any changes.
+ */
+async function writeApiIndexMdx({ docpath, apiName }) {


❓ Question: How do we feel about making this more clear and creating a title, and description configuration. This way we can change the values that get passed in (for translations or otherwise).

mikemimik · 2026-02-24T21:11:40Z

scripts/artifact-generation.js

+  } catch {
+    // File doesn't exist, create it
+    try {
+      await fs.writeFile(indexFilePath, indexContent);
+    } catch (err) {
+      console.error(`failed to write index: ${indexFilePath}`, err);
+    }
+  }


🤔 This can technically fail for user access reasons. What do you think about using stat instead? The only reason fs.stat throws is if the file doesn't exist.

mikemimik · 2026-02-24T23:19:42Z

scripts/artifact-generation.js

      docsJson.navigation.languages[langIdx].tabs[refIdx].dropdowns.push({
        dropdown: oasConfig.docSectionNameMap[locale],
        icon: "list",
+        openapi: specPath,


✋🏽 Change Request: I think we're going to need to remove this as when this property is included the sidebar structure is not what we're expecting.

Removing this, means that we don't require specPath at multiple locations, we can probably remove the getOasFilePath function, which removes the need for patchDocsJson to be an async function.

mikemimik · 2026-02-24T23:20:54Z

scripts/artifact-generation.js

+    // and ensure the openapi field is always present
    docsJson.navigation.languages[langIdx].tabs[refIdx].dropdowns[
      apiIdx
-    ].pages = [`${docsPath}/index`, docsByLocale[locale]];
+    ].openapi = specPath;


Ref previous comment - ref

agiannelli-auth0 added 2 commits February 19, 2026 15:39

fix: update script to ensure docs loads up properly

6b8c5fc

feat: generate files for MyAccount API

f2619e6

agiannelli-auth0 marked this pull request as ready for review February 19, 2026 20:54

agiannelli-auth0 requested review from a team as code owners February 19, 2026 20:54

mintlify bot deployed to staging - main February 19, 2026 20:57 View deployment

feat: add code snippets to myaccount-api-oas

81da17e

mintlify bot deployed to staging - main February 19, 2026 21:14 View deployment

nlucero reviewed Feb 20, 2026

View reviewed changes

...count/authentication-methods/confirm-the-enrollment-of-a-supported-authentication-method.mdx Outdated Show resolved Hide resolved

scripts/artifact-generation.js Show resolved Hide resolved

agiannelli-auth0 added 3 commits February 20, 2026 11:28

fix: update script to fallback to english OAS when locale-specific do…

10a9730

… not

fix: add/update tests

1c98b97

fix: update patchDocsJson tests

3f93df8

mintlify bot deployed to staging - main February 20, 2026 17:23 View deployment

fix: remove duplicate code samples

9d35295

mintlify bot deployed to staging - main February 20, 2026 18:48 View deployment

fix: properly implement OAS registration & simplify front-matter

0d29c37

mintlify bot deployed to staging - main February 20, 2026 19:38 View deployment

nlucero reviewed Feb 23, 2026

View reviewed changes

fix: reimplement getOasPath

23dd7ad

mintlify bot deployed to staging - main February 23, 2026 20:14 View deployment

nlucero reviewed Feb 24, 2026

View reviewed changes

nlucero approved these changes Feb 24, 2026

View reviewed changes

mikemimik requested changes Feb 24, 2026

View reviewed changes

		@@ -0,0 +1,9 @@
		---
		openapi: post /authentication-methods/{authentication_method_id}/verify

Comments

Conversation

agiannelli-auth0 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes:

References

Testing

Checklist

Uh oh!

Uh oh!

Uh oh!

nlucero commented Feb 20, 2026

Uh oh!

agiannelli-auth0 commented Feb 20, 2026

Uh oh!

agiannelli-auth0 commented Feb 20, 2026

Uh oh!

agiannelli-auth0 commented Feb 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlucero Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

agiannelli-auth0 commented Feb 19, 2026 •

edited

Loading

nlucero Feb 24, 2026 •

edited

Loading