DEV Community: Kate Bartolo

Rendering Remote Content in Astro Using React Components

Kate Bartolo — Thu, 06 Aug 2026 12:15:20 +0000

Here's the problem: You want to pull remote Markdown into your site, but you want components with interactivity like syntax highlighting or copy buttons, not plain HTML. On Astro, this means you're on your own, since there's no built-in way to use custom components with remote Markdown or MDX.

I hit this wall when trying to fetch posts from dev.to and render them using custom components, like a CodeBlock component, without triggering a layout flash.

The source content for this post is my dev.to blog, but the problem applies to any remote Markdown: a CMS, a Jekyll blog, a GitHub wiki.

Note: I built astro-mdx-remote to solve this problem automatically. But read on to find out how it all works!

Code samples use Astro 5.0+ Content Layer APIs. The code is simplified for clarity. You may need to adapt the loader and schema to match your content source.

Why Not Astro Islands?

Astro Islands are Astro's built-in hydration system.

Astro Islands work by scanning your component references at build time. When you write <MyReactComponent client:load />, Astro knows exactly which component to hydrate and bundles it accordingly. But remote content arrives at runtime as a string, so there's nothing for Astro to scan. Any components aren't referenced anywhere in the source tree, which means Astro can't manage the hydration for them.

To make this work, you can't use Astro components in your MDX (Astro will only compile those at build time), and you have to bypass Astro's MDX pipeline.

The Baseline: Plain HTML Rendering

The following is the basic shape the other experiments branch off of. You must fetch the dev.to articles and store them using an Astro content loader.

The baseline means using Astro's pipeline to load the remote Markdown, store it as HTML in a content collection, then render it with Astro's render(). This works fine for plain Markdown content. There is no component control, but your posts are live on your site.

The following example creates a loader that fetches articles and renders the raw Markdown to HTML using Astro's renderMarkdown:

// Loader
function devToLoaderBase(username: string): Loader {
  return {
    name: 'devto-loader-baseline',
    load: async ({ store, parseData, generateDigest, renderMarkdown }) => {
      const articles = await fetchDevToArticles(username);
      store.clear();

      for (const article of articles) {
        const { id, data, digest } = await parseArticle(article, {
          parseData,
          generateDigest,
        });
        store.set({
          id,
          data,
          digest,
          rendered: await renderMarkdown(article.body_markdown),
        });
      }
    },
  };
}

export const collections = {
  devToBaseline: defineCollection({
    loader: devToLoaderBase('username'),
    // Schema matches the dev.to data payload shape (`data` above)
    schema: z.object({
      title: z.string(),
      slug: z.string(),
      description: z.string(),
      publishedAt: z.date(),
      markdown: z.string(),
      html: z.string(),
    }),
  }),
}

You can then create a dynamic router to render the fetched Markdown in an Astro layout. Astro will automatically use the rendered HTML data:

// [...slug].astro
---
import { getCollection, render } from 'astro:content';
import Blog from '../layouts/Blog.astro';

export async function getStaticPaths() {
  const posts = await getCollection('devToBaseline');

  return posts.map((post) => ({
    params: { slug: post.data.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---

<Blog {...post.data}>
  <Content />
</Blog>

See it live: This is just HTML, no fancy code blocks yet.

Finding: This is good enough if you don't need components. But what happens when you do?

Experiment 1: Client Islands

Idea: Add data-component attributes and then mount React components into them.

Instead of using Astro's renderMarkdown, you can create your own client island. First, in your loader, inject a custom rehype plugin (rehypeComponentMarkers) that adds data-component attributes to elements:

import matter from 'gray-matter';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import rehypeComponentMarkers from './plugins/rehype-component-markers';

export function devToLoaderRehype(username: string): Loader {
  return {
    name: 'devto-loader-rehype',
    load: async ({ store, parseData, generateDigest }) => {
      const articles = await fetchDevToArticles(username);
      ...

      for (const article of articles) {
        // ...

        // Extract body content (gray-matter strips frontmatter)
        const { content } = matter(article.body_markdown);

        // Use rehype to add component markers
        const file = await unified()
          .use(remarkParse)
          .use(remarkRehype)
          .use(rehypeComponentMarkers)
          .use(rehypeStringify)
          .process(content);

        // Set the custom HTML in the collection store directly
        store.set({
          id,
          data,
          digest,
          rendered: {
            html: String(file),
            metadata: { headings: [], imagePaths: [], frontmatter: {} },
          },
        });
      }
    },
  };
}

Here's what the rehypeComponentMarkers might look like for just the pre element:

import { visit } from 'unist-util-visit';
import type { Root, Element } from 'hast';

export default function rehypeComponentMarkers() {
  return (tree: Root) => {
    visit(tree, 'element', (node: Element) => {
      if (node.tagName === 'pre') {
        const codeChild = node.children.find(
          (child): child is Element =>
            child.type === 'element' && child.tagName === 'code',
        );
        const lang =
          codeChild?.properties?.className
            ?.toString()
            .replace('language-', '') ?? 'text';

        node.properties = {
          ...node.properties,
          'data-component': 'code-block',
          'data-language': lang,
        };
      }
      // handle other elements

This adds attributes to your HTML by mapping pre to code-block and setting the code language string (in this case "js"):

<pre data-component="code-block" data-language="js">...</pre>

Rehype can enrich the HTML but can't inject server-rendered components itself. Rehype operates on string/AST transformations during the loader phase, outside React's runtime.

On the client side, you can query the DOM after load, and then mount React components into the data attributes using createRoot.

From your [...slug].astro route, get the new collection, and add a client-side script:

// [...slug].astro
---
export async function getStaticPaths() {
  const posts = await getCollection('devToRehype');
  ...
---

...

<script>
  import { createElement } from 'react';
  import { createRoot } from 'react-dom/client';
  import CodeBlock from '../components/CodeBlock';

  document.querySelectorAll('[data-component="code-block"]').forEach((node) => {
    const code = node.querySelector('code')?.textContent ?? '';
    const language = node.getAttribute('data-language') ?? undefined;

    const root = createRoot(node);
    root.render(createElement(CodeBlock, { code, language }));
  });
</script>

See it live: Inspect the page to look for the data-component attributes. The CodeBlock component renders, but there is a significant flash where you see the HTML first, then the component mounted inside the wrapper.

This works, but createRoot discards the server-rendered HTML and remounts from scratch, causing a visible flash.

Switching to hydrateRoot will not fix the flash. hydrateRoot expects to find HTML that already matches the component's output, since it attaches event listeners to existing markup rather than replacing it. But that contract requires the server to have rendered the component in the first place.

In this experiment, the server only produced plain <pre> HTML, so hydrateRoot has nothing valid to attach to. It will throw a mismatch warning and recover by re-rendering, which is exactly the same outcome as createRoot.

Finding: The flash is a server-rendering problem. To fix the flash, the React component's HTML needs to be in the page before the client loads.

The Real Problem: Hydration Requires Server-Rendered HTML

To get component HTML into the page without a flash, the React component needs to be rendered on the server before it's mounted on the client. That's what hydration is: the server renders the HTML first, the client attaches to it.

Hydration in our case requires:

A way to compile a raw MDX string at runtime. Since Astro's pipeline requires files on disk at build time, we cannot use it for the remote case.
A way to intercept the component rendering on the server to wrap each one in a hydration island.

Astro's render() gives you a <Content /> component, but you can't intercept it to server-render each component individually. The solution is to bypass Astro's MDX pipeline and do the render yourself.

Experiment 2: MDX Compiler

Idea: Instead of using Astro's pipeline, we can compile the raw Markdown string at runtime using @mdx-js/mdx itself:

import { compile, run } from '@mdx-js/mdx';
import * as runtime from 'react/jsx-runtime';
import type { MDXContent } from 'mdx/types';

async function compileMdx(content: string): Promise<MDXContent> {
  const compiled = String(
    await compile(content, { outputFormat: 'function-body' }),
  );
  const { default: MDXContent } = await run(compiled, {
    ...runtime,
    baseUrl: import.meta.url,
  });
  return MDXContent;
}

This requires telling the server how to map the pre and code HTML to the CodeBlock component.

You can't pass CodeBlock directly because MDX compilation gives the pre a children prop (the nested code element) rather than the code and language props that CodeBlock expects. Below, PreWrapper bridges that gap by extracting what it needs from the children:

// src/components/PreWrapper.tsx
import CodeBlock from '../components/CodeBlock';
import { type ReactElement } from 'react';

interface CodeChild {
  children?: string;
  className?: string;
}

export default function PreWrapper({ children }: { children?: ReactElement<CodeChild> }) {
  const code = children?.props?.children ?? '';
  const language = children?.props?.className?.replace('language-', '') ?? '';
  return <CodeBlock code={code} language={language} />;
}

The compileMdx function creates a component that takes a components map, which you can use to map those compiled pre elements to your PreWrapper function:

// [...slug].astro
---
...

const MDXContent = await compileMdx(post.data.markdown);
---
<BlogPost {...post.data}>
  <MDXContent components={{ pre: PreWrapper }} />
</BlogPost>

See it live: The component should render with no flash! But the Copy button doesn't work, since the server rendered the component's HTML, but React hasn't attached to it yet. Event listeners like the Copy button's onClick are never added.

Experiment 3: Server Render + Hydration Islands

With Experiment 2, the server and client HTML now match, preventing the flash. To make interactive components like CodeBlock work, the client now has to attach to the existing HTML.

First, this requires an island wrapper function to add data attributes (like the rehype example above) that tell the client JS where and how to hydrate the server-rendered HTML:

// Server-side function
function renderIsland(name: string, Component: ComponentType<any>, props: Record<string, unknown>) {
  // Children aren't serializable, so we pass them to renderToString but not data-props
  const { children, ...serializableProps } = props;
  const staticHtml = renderToString(createElement(Component, props));
  return createElement('div', {
    className: 'remote-island',
    'data-component': name,
    'data-props': JSON.stringify(serializableProps),
    // Make sure you trust the HTML source
    dangerouslySetInnerHTML: { __html: staticHtml },
  });
}

The renderIsland replaces PreWrapper, which only mapped props and returned the component directly.

The renderIsland function does the same mapping but also returns an HTML element wrapper with data-component and data-props attributes, to name the component and serialize the props explicitly. Note that each div this creates is given the class name "remote-island".

Important Caveat: Children are passed to renderToString so the server can produce the initial HTML, but they're excluded from data-props because React elements aren't JSON-serializable. Only plain props like strings, numbers, or booleans go into the data attribute for the client to read back. So this method only works with serializable props.

You can now use this function in the component map to ensure your component is wrapped in an island div:

// [...slug].astro
---
import CodeBlock from '../components/CodeBlock';
import type { ComponentType, ReactElement } from 'react';

interface CodeElementProps {
  children?: string;
  className?: string;
}

...

const pageComponents = {
  pre: (props: Record<string, unknown>) => {
    const children = props.children as ReactElement<CodeElementProps> | undefined;

    return renderIsland('CodeBlock', CodeBlock, {
      code: children?.props?.children ?? '',
      language: children?.props?.className?.replace('language-', '') ?? '',
    });
  }
};

---
<BlogPost {...post.data}>
  <MDXContent components={pageComponents} />
</BlogPost>

The client script can get all divs by class "remote-island", read the props, and call hydrateRoot with the component and props:

<script>
  // import { createElement } from 'react', etc.
  import CodeBlock from '../components/CodeBlock';

  const components: Record<string, ComponentType<any>> = { CodeBlock };

  document.querySelectorAll('.remote-island').forEach((node) => {
    const name = node.getAttribute('data-component');
    const props = JSON.parse(node.getAttribute('data-props') || '{}');
    const Component = components[name!];
    if (!name || !Component) return;

    hydrateRoot(node as HTMLElement, createElement(Component, props));
  });
</script>

See it live: Finally, no flash, and the Copy button works! Inspecting the page should show the "remote-island" divs wrapping the CodeBlock code.

Finding: This works, but note that you have to manually import every component on both server and client, which could be hard to maintain if you have more than 1 or 2 components.

Conclusion

The flash is a server-rendering problem. The solution is to server render the component first, then hydrate it.

From the server, mark an element so the client knows it needs to become interactive.
Make sure the component's initial HTML is already in the page (server-rendered) before the client loads.
Reattach the React component to that existing HTML on the client, without removing and re-rendering from scratch.

Two constraints to keep in mind:

You can only render components with serializable props.
You have to import each component on both the server and client sides.

For this to work in practice on more than a few components, you would need a Vite virtual module to handle passing components to both the server and client sides.

I built a package to handle that: astro-mdx-remote. It handles the virtual module, runtime MDX compilation, server-side island wrapping, and client hydration automatically. You can register your components once, and the package handles the rest!

Are you fetching remote content from dev.to for your blog site or another source? I'd love to hear about it.

Cover photo by Jonathan Cooper on Unsplash

How to Document an Express API with Swagger UI and JSDoc

Kate Bartolo — Sun, 29 Nov 2020 19:01:33 +0000

JSDoc is a popular tool for generating documentation from comments in the source code of your app. This serves two purposes. First, the documentation is directly available to anyone viewing the source code. Second, the comments can be compiled later into a complete set of reference documentation.

Swagger provides a tool for presenting this documentation: Swagger UI. Swagger UI creates a web page from OpenAPI Specification definitions. As this tutorial will show, these definitions can be written in YAML directly in JSDoc comments.

In this tutorial, you will set up a Swagger UI documentation web page for an Express API. You can then write JSDoc comments in your API's source code to generate the OpenAPI definitions. By the end, you will have documentation that follows the OpenAPI Specification, presented from a custom /docs endpoint added to your Express API:

Prerequisites

To complete this tutorial, you'll need

Familiarity with REST APIs and Express
Node.js installed on your system
An Express-based REST API running on a local Express server. If you don't have one, you can install the Express API used in this tutorial. It retrieves user data from JSONPlaceholder.

To install and run the sample Express API, first clone the repository (replace test-api with the directory name of your choosing):

git clone https://github.com/kabartolo/jsonplaceholder-express-api test-api

Next, run the following commands to start the Express server (replace test-api with the name of the directory you just created):

cd test-api
npm install
npm run start

Navigate to localhost:3000 to see the API. You should see links to /users and /users/1.

Navigate to either of these to see user data from JSONPlaceholder.

The code added during this tutorial can be found in the repository's docs branch.

Terminology

OpenAPI is the name of the specification, while Swagger is the set of tools that implement this specification. See What Is the Difference Between Swagger and OpenAPI?

This tutorial uses the following API-related terms and definitions defined by OpenAPI:

    https://api.example.com/v1/users?role=admin&status=active
    \________________________/\____/ \______________________/
             server URL       endpoint    query parameters
                                path

Server URL or base URL: The base URL for all API endpoints: localhost:3000 or example.com/api
Endpoint path: The path representing the location of the resource (relative to the base URL): /users or /users/1
Operation: The HTTP method used to manipulate endpoint paths: GET, POST, PUT, DELETE
Resource: Information representing a real-world object (e.g., a user or book), usually returned by the API as JSON data. Represented by a database model in Express.

The full URL used to retrieve data from the API is formed by adding the endpoint to the base URL: localhost:3000/users.

Step 1: Set up the application

1.1: Install `swagger-jsdoc` and `swagger-ui-express`

To create a Swagger UI page from JSDoc comments, you’ll need a way to pass your documentation to Swagger UI:

swagger-jsdoc generates OpenAPI definitions from JSDoc comments.
swagger-ui-express creates the Swagger UI page from these definitions.

To install swagger-jsdoc and swagger-ui-express to your Express API, run

npm install swagger-jsdoc@5.0.1 --save-exact
npm install swagger-ui-express --save

This tutorial uses swagger-jsdoc version 5.0.1. The latest version might not be compatible with this tutorial.

1.2: Create an API specification

Swagger UI creates a docs page from a set of OpenAPI definitions. These definitions are written in YAML or JSON to describe a REST API. For more information on the basic structure of the OpenAPI Specification, see Basic Structure.

In your Express API's app.js file, add the following code below the list of required modules:

// app.js
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  openapi: '3.0.0',
  info: {
    title: 'Express API for JSONPlaceholder',
    version: '1.0.0',
  },
};

const options = {
  swaggerDefinition,
  // Paths to files containing OpenAPI definitions
  apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

The swaggerDefinition object (i.e., the OpenAPI definition) defines the root information for your API. Provide a few basic pieces of information to the swaggerDefinition, such as the title and version of your API; you can fill in more later.

The options object contains this swaggerDefinition object and an array of paths called apis. These are paths to files containing other OpenAPI definitions. These file paths should be relative to the root directory of your Express API. In our case, definitions will be written in JSDoc directly in the /routes files. You can list the filenames individually or use the wildcard delimiter * to add all JavaScript files in a directory, as shown above.

The options object is used by swagger-jsdoc to produce an OpenAPI specification in a variable called swaggerSpec. This specification is equivalent to the swagger.json or swagger.yaml file normally used by Swagger UI to create a docs page. You'll pass this object to Swagger UI in the next step.

Restart the Express server to ensure there are no errors. If you get any errors at this stage, check that your swagger-jsdoc version is 5.0.1 exactly.

1.3: Create the Swagger UI docs page

To create a Swagger UI page for your Express API, include swagger-ui-express in the app.js file. Then, add an endpoint path called /docs (or any name of your choosing):

// app.js
// ...
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// ...

var app = express();

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

As shown above, swagger-ui-express provides two callbacks to set up the endpoint: one to set up Swagger UI with the swaggerSpec definitions and one to serve it to the /docs endpoint.

Restart the Express server, and navigate to localhost:3000/docs in the browser.

You'll see the title and version number of your Express API, as well as the OpenAPI version number (3.0.0). Since we have no other definitions yet, you'll see a "No operations defined in spec!" message:

You now have the start of a beautiful docs page for your API! The rest of this tutorial provides a basic introduction to OpenAPI definitions.

Step 2: Define your API's root information

You've created a Swagger UI docs page, and you're set to start writing docs. But first, you should add more root definitions for the API.

Return to app.js. Note that the info object maps to OpenAPI's Info Object to define a title, description, list of servers, contact information, and list of paths for your API.

Here is an example of a more complete definition:

// app.js
const swaggerDefinition = {
  openapi: '3.0.0',
  info: {
    title: 'Express API for JSONPlaceholder',
    version: '1.0.0',
    description:
      'This is a REST API application made with Express. It retrieves data from JSONPlaceholder.',
    license: {
      name: 'Licensed Under MIT',
      url: 'https://spdx.org/licenses/MIT.html',
    },
    contact: {
      name: 'JSONPlaceholder',
      url: 'https://jsonplaceholder.typicode.com',
    },
  },
  servers: [
    {
      url: 'http://localhost:3000',
      description: 'Development server',
    },
  ],
};

If you have a production server, add the URL and a description to the servers list. See Basic Structure for more information on the other properties you can add to the root definition.

In the OpenAPI docs, you'll notice there's also a paths field. You won't need to specify the path definitions here, since each path is defined separately in a JSDoc comment (to be added in the next step). These path definitions are compiled by swagger-jsdoc into a paths object for you.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You should see more information about your API at the top of the docs page:

You can now start documenting your Express routes.

Step 3: Write the docs

With a Swagger UI docs page available at the /docs endpoint and a complete set of root information on your API, you can start writing your path definitions. Each path definition corresponds to an Express route in your API. It describes both the operation and endpoint path, such as GET /users and DELETE /users/:id.

3.1: Document the routes

To document /routes/users.js, first add a comment starting with @swagger above the first route. Follow this with some basic information about the route:

// routes/users.js

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of JSONPlaceholder users
 *     description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
*/
router.get('/', function(req, res) {
  //...
});

Note that swagger-jsdoc looks for comments with a @swagger or @openapi tag to create OpenAPI definitions.

As shown in the code example, add the endpoint path /users and the operation get (indented two spaces). The path in the Express router function get('/') is relative to /users, so the path in the definition should be /users.

The summary should be a brief description of the goal of this route. The description should provide more detail, such as when or why you would want to use the route.

Be sure to use two spaces (or four spaces) for indentation, not tabs. Refer to YAML Syntax for more information.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You should see a listing for GET /users near the bottom of the page:

3.2: Document responses

Your users will want to know what is returned when this GET request is successful (i.e., with a status code of 200). To define a successful response, add a responses object and a response called 200 to the path definition:

// routes/users.js

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of JSONPlaceholder users.
 *     description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
 *     responses:
 *       200:
 *         description: A list of users.
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: integer
 *                         description: The user ID.
 *                         example: 0
 *                       name:
 *                         type: string
 *                         description: The user's name.
 *                         example: Leanne Graham
 */
router.get('/', function(req, res) {
  //...
});

The description field describes the response or what it returns. The content field describes the content type (application/json), and the schema describes the response object. In our case, JSONPlaceholder returns an object with a data field, which contains the data you've requested. For this response, data contains an array of user objects. Add just one or two user properties (e.g., id and name) to avoid cluttering the file for now.

Add a real example value for each property (e.g., 'Leanne Graham'); otherwise, Swagger UI creates a generic example such as 'string'.

Notice how the types are defined in this schema. For example, to define an array, add type: array and an items field. Read more about types in the Data Types documentation.

You can also describe error responses this way. See Swagger's Describing Responses documentation for more details on the fields available for describing each response.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You should see the response, an example value (using the example values you provided for each property), and the schema for the data returned in this response:

Next, define the GET /users/:id path by adding the fields we've covered already (summary, description, and responses):

// routes/users.js

 /**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Retrieve a single JSONPlaceholder user.
 *     description: Retrieve a single JSONPlaceholder user. Can be used to populate a user profile when prototyping or testing an API.
 *     responses:
 *       200:
 *         description: A single user.
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: integer
 *                       description: The user ID.
 *                       example: 0
 *                     name:
 *                       type: string
 *                       description: The user's name.
 *                       example: Leanne Graham
*/

router.get('/:id', function(req, res) {
  //...
});

Here, the path parameter (id) is added to the endpoint path: /users/{id}. Curly brackets ({}) are used to mark a path parameter in the endpoint path. Note that the colon style (/users/:id) won't work with Swagger (thanks @sherwinwater for pointing this out!).

The data object in this schema contains a single user object instead of an array of user objects, but the properties are the same.

Next, define POST /users by adding the fields we've covered already (summary, description, and responses):

// routes/users.js

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Create a JSONPlaceholder user.
 *     responses:
 *       201:
 *         description: Created
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: integer
 *                       description: The user ID.
 *                       example: 0
 *                     name:
 *                       type: string
 *                       description: The user's name.
 *                       example: Leanne Graham
*/
router.post('/', function(req, res) {
// ...
});

A successful response in this case would be 201. It returns an object with a data field containing the new user.

You can continue adding path definitions for the remaining routes in the same way. We'll do some refactoring in a later step.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You'll now see a listing for GET /users/{id}, POST /users, and any other path definitions you've added:

3.3: Document the requests

Request data such as parameters and request bodies can also be documented in your OpenAPI definitions. For example, GET /users/:id has an id parameter, which should be documented.

To document parameters, add a parameters field to the path definition:

// routes/users.js

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Retrieve a single JSONPlaceholder user.
 *     description: Retrieve a single JSONPlaceholder user. Can be used to populate a user profile when prototyping or testing an API.
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: Numeric ID of the user to retrieve.
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         ...
 */
router.get('/:id', function(req, res) {
  //...
});

In the definition for this parameter, in defines the parameter's location (in this case, it's a path parameter because it's part of the path). You can also add a name, description, and schema and whether the parameter is required. See Describing Parameters for more details.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You'll see a list of parameters for this route:

Next, document the request body for POST /users to describe the data required to create a new user in the database. To do this, add a requestBody field to this path definition:

// routes/users.js

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Create a JSONPlaceholder user.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               name:
 *                 type: string
 *                 description: The user's name.
 *                 example: Leanne Graham
 *     responses:
 *       201:
 *         ...
*/
router.post('/', function(req, res) {
// ...
});

This adds a request body schema to this path definition. This example shows that name can be sent in the request body. You can add more properties for new users later. See Describing Request Body for more details.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You'll see a section called Request body with the schema you've provided:

3.4: Document the resources

You might have noticed you've repeated the user schema several times in the documentation so far. To avoid this duplication, you can define the user schema in one place and reference it from elsewhere.

Each model defined by your Express API can be documented separately as a schema definition (or component). To do this for the user model, add a User schema definition to the top of the file, under components/schemas:

// routes/users.js

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           description: The user ID.
 *           example: 0
 *         name:
 *           type: string
 *           description: The user's name.
 *           example: Leanne Graham
 */

You can then reference this schema definition using $ref:

// routes/users.js

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of JSONPlaceholder users
 *     description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
 *     responses:
 *       200:
 *         description: A list of users.
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
router.get('/', function(req, res) {
  //...
});

The $ref path uses JSON Reference notation. The # symbol indicates the root of the current document, and the remaining nested values are then resolved in order. For more information, see Using $ref.

Restart the Express server, and navigate again to localhost:3000/docs in the browser. Your path definitions will now use this User schema, and you should see a schema definition for User at the bottom of the page:

Similarly, you can define a NewUser object to reference in the POST /users request body. Since it contains some but not all of the fields from the User schema, you can also use $ref to avoid duplication between them:

/**
 * @swagger
 * components:
 *   schemas:
 *     NewUser:
 *       type: object
 *       properties:
 *         name:
 *           type: string
 *           description: The user's name.
 *           example: Leanne Graham
 *     User:
 *       allOf:
 *         - type: object
 *           properties:
 *             id:
 *               type: integer
 *               description: The user ID.
 *               example: 0
 *         - $ref: '#/components/schemas/NewUser'
 */

The allOf keyword combines model definitions, in this case the NewUser definition (containing the name property) and an object with an id property. See oneOf, anyOf, allOf, not for more details.

You can now reference NewUser from the request body definition for POST /users:

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Create a JSONPlaceholder user.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/NewUser'
 *     responses:
 *       201:
 *         ...
*/
router.post('/', function(req, res) {
  // ...
});

Restart the Express server, and navigate again to localhost:3000/docs in the browser. You'll see your NewUser schema in the request body definition for POST /users:

This covers the basic techniques for producing OpenAPI definitions in JSDoc comments.

Conclusion

You are now set up to produce a complete reference documentation page for your Express API. You've created a basic set of OpenAPI definitions and a Swagger UI page that displays them. If you want more practice with the OpenAPI Specification, you can finish documenting the jsonplaceholder-express-api.

This tutorial has also covered the basics of writing OpenAPI definitions. To complete your documentation, consult the OpenAPI Specification and the Swagger Docs.

To see a version of the jsonplaceholder-express-api that includes all the code added during this tutorial, see the repository's docs branch.

DEV Community: Kate Bartolo

Rendering Remote Content in Astro Using React Components

Why Not Astro Islands?

The Baseline: Plain HTML Rendering

Experiment 1: Client Islands

The Real Problem: Hydration Requires Server-Rendered HTML

Experiment 2: MDX Compiler

Experiment 3: Server Render + Hydration Islands

Conclusion

How to Document an Express API with Swagger UI and JSDoc

Prerequisites

Terminology

Step 1: Set up the application

1.1: Install swagger-jsdoc and swagger-ui-express

1.2: Create an API specification

1.3: Create the Swagger UI docs page

Step 2: Define your API's root information

Step 3: Write the docs

3.1: Document the routes

3.2: Document responses

3.3: Document the requests

3.4: Document the resources

Conclusion

1.1: Install `swagger-jsdoc` and `swagger-ui-express`