<api-viewer>: document your Web Components API
Tags: webcomponents, customelements, javascript, html
Published: 2019-10-22 13:16:27

---
title: <api-viewer>: document your Web Components API
published: true
description: A custom element for documenting Web Components, consuming JSON output generated by Web Component Analyzer.
tags: webcomponents, customelements, javascript, html
cover_image: https://thepracticaldev.s3.amazonaws.com/i/x3pte6vq2gi3b3555rij.png
---

Building Web Components is something I enjoy, and it is really easy to create one using [LitElement](http://lit-element.polymer-project.org). However, the ecosystem around LitElement is not quite mature yet, and sometimes we don't have a replacement for certain important tools we used to have while developing with Polymer.

Documenting is one such missing piece. While we can use Storybook with a preset by [open-wc.org](https://open-wc.org/demoing/) for showcasing different states of our components, there is a thing that we are lacking: a simple tool to browse the API docs. This is exactly what the component I'm sharing today is intended to be.

## What?

Meet the [`<api-viewer>`](https://github.com/web-padawan/api-viewer-element) element! It is built with LitElement and TypeScript. Check out the [live demo](https://api-viewer-element.netlify.com) to see what kind of documentation it provides.

Note, this is just 0.1.0 release and I have a lot of ideas on how to improve the API viewer. Also, the idea behind this component is that we might use it for [Vaadin components](https://vaadin.com/components) in the future, so there might be some "internal" feature requests over time, but the community feedback is always welcome.

## Why?

While we can still use `polymer-analyzer` tool and [`<iron-component-page>`](https://github.com/PolymerElements/iron-component-page) component by the Polymer team with LitElement and [document]((https://polymer-library.polymer-project.org/3.0/docs/tools/documentation)) properties, methods and events, it starts getting complicated if we switch to TypeScript. Also, these components and tools are no longer actively updated.

Thankfully, there is a [web-component-analyzer](https://github.com/runem/web-component-analyzer), a CLI tool by [Rune Mehlsen](https://github.com/runem). It provides the ability to extract properties, attributes, methods, events, slots and custom CSS properties of the custom elements and outputs analysis as markdown or JSON (including the format [proposed](https://github.com/w3c/webcomponents/issues/776) by VSCode team).

I was looking for a web component compatible with the Analyzer, and I found [`<wc-info>`](https://github.com/bahrus/wc-info) by [Bruce B. Anderson](https://github.com/bahrus). While I like the general idea, the component is still not exactly what I needed. So I decided to go ahead and build the `<api-viewer>` from scratch, and in a few days I built an MVP.

## How?

Here is a minimal usage example which you can run using [es-dev-server](https://open-wc.org/developing/es-dev-server.html):

```html
<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import 'api-viewer-element';
    </script>
  </head>

  <body>
    <api-viewer src="./custom-elements.json"></api-viewer>
  </body>
</html>
```


Follow the full [usage instructions](https://github.com/web-padawan/api-viewer-element#usage) to learn how to generate the JSON file. The Web Component Analyzer [documentation](https://github.com/runem/web-component-analyzer#-how-to-document-your-components-using-jsdoc) is also worth checking.

And of course, let me know if you have any comments, feature requests or any other feedback regarding `<api-viewer>`. Let's make it better together!