Elements CLI Preview

[marbemac]

Intro & Goal

As a non-Studio user, working in Vim or any other text editor, I want to see how my docs will look in Elements without having to make an index.html file and embed the component somewhere. Support in my text editor would be amazing, but as a fall-back having a CLI tool to use would be ok too.

Who's it for?

• Any OpenAPI user who wants to "preview" their API refererence docs without an account, or having to push or upload things.

• Swagger UI / ReDoc users who want something nicer and more functionality to look at whilst building OpenAPI in their favourite not-Stoplight editor.

• Elements users trialing elements out.

Why build it?

• A simple CLI exists for every popular API documentation tool: ReDoc, Swagger UI, Spectacle

• Let people play around with elements without needing to make somewhere to embed the component

What is it?

• Runs a server instance which is just the API component embedded in a index.html file and served up on localhost:8XXX/ so that folks can open it in their browser.

• elements preview openapi.yamlto autodetect type of thing to preview. For now, only APIs are supported. In future we can offerelements preview --api=openapi.yamlto be more specific, but dont need it yet.

• --watch option to have it reload when changes are made to the files its looking at (wont work for project, its ok just ignore it)

• elements export openapi.yaml -o foo.html option to leverage the existing Static Export we created elsewhere without forcing users to download swagger-cli or write JavaScript.he server.

• Embed basic anonymous tracking in place to get a sense of usage. Dealers choice on exactly what but something we generally use elsewhere too.

Out of Scope

We will not be offering previews for projects, articles, or models at this time, only APIs.

Key Success Criteria

• Double the Stoplight CLI downloads (from 8,000 to 16,000) within 2 months of release

[marbemac]

Link to feature: https://stoplightio.productboard.com/feature-board/planning/features/6218077

[marcelltoth]

Questions regarding the spec:

1. Don't we want a --port option?
2. Can we consider making the export a separate command? Could be export-preview to make it similar, but it does something soo different that it would feel out of place to force it into the same command.

• Pretty much every option we define for preview would make no sense for export-preview: --port, --watch, --ssl, etc.
• OTOH the export path option doesn't make sense for the HTML export.
• That way we could make the syntax stoplight export-preview in.spec.yaml out.html or stoplight export-preview in.spec.yaml > out.html and support piping for people who want it. (Fairly trivial, if we don't have a second arg we output to stdout.) Or even cat in.spec.yaml | stoplight export-preview | do-whatever if you wanna go that far, also fairly trivial to implement.
• That's what redoc does, too.

3. I don't quite get this part.

   to leverage the existing Static Export we created elsewhere without forcing users to downoad swagger-cli or write JavaScript.he server.

   Is there an issue for the static export functionality? If so let's link it. But it looks to me that the preview command depends on the static export function anyway, because it's really a static export plus a server. So probably it should be part of the scope here.

4. Do we want to serve / export completely self-sufficient files (they'll be like ~6+MB, lots of repeated content but don't need internet connection), or ones that are single-file, but still load elements itself from unpkg? Fun part about that would be that it essentially auto-updates.

5. What's the $ref handling policy? Bundle $refs before export?

Embed basic anonymous tracking in place to get a sense of usage. Dealers choice on exactly what but something we generally use elsewhere too.

We'll probably need guidance from @smf434 & team here (do you have a team-alias on Github?). We don't seem to have any sort of tracking in the CLI. We'd need to figure out what needs to be tracked an using what format.

[steve-nay-sage]

As a technical writer, I was really excited to start reading about this feature. Then I got to the Out of Scope section:

"We will not be offering previews for projects, articles, or models at this time, only APIs."

That makes this just another OpenAPI definition formatter. Why bother? There are already several of those available from other developers; it's not as if people are blocked by not being able to find a tool that lets them preview a pretty version of their OpenAPI definition on their local machine.

What I really need is a version of Elements Dev Portal on my local machine -- that would actually be useful for people who recognize that documentation is more than just an API reference. By the way, I think Stoplight says exactly that on their website. ;-)

[philsturgeon]

Hey @steve-nay-sage!

If you're using Elements Dev Portal, and you want to take a look at that on your local machine, you can follow the instructions here and with one HTML file and one http-server you're up and running.

The idea of Elements, especially the dev portal extension, is that you're combining it with your own HTML and CSS for the sake of customization, so the CLI preview is never going to give you parity. We're just trying to make previews easier for more people, and the easiest use case is Elements CLI.

Why? Well, we build everything iteratively, MVP, measure, improve, repeat. Building elements preview openapi.yaml is a whole lot easier than hooking up project tokens and API interactions, and we'll see how much that gets used before putting extra time into working on extra functionality.

For future context, something being out of scope now doesn't mean it wont be done in a followup PR, so we'll take your feedback as a vote for Elements Dev Portal Preview. 🙌

[philsturgeon]

@noor-ahmad @mnaumanali94 it could be nice to get the Elements CLI conversation going again, at least get a solid plan on what functionality will be needed in the first go (preview, export html, static export - aka no dependencies, watch files, etc).

The main primary use-case is "dont make people write HTML to see Elements docs" but from there you can add on infinite other functionality. Which port should it run on, so it can maybe fit into docker/k8s containers. Which host should it run on, so it can potentially be deployed? Do we want to let people pick stacked layouts, hide mocking, all the other things we offer as component config. There's a lot to figure out.

[philsturgeon]

Btw Speccy was the easiest thing in the world. It just wrapped the HTML and spat it out on a server. This would honestly be a great start for us. We could do that as local files and dev portal projects easy enough. https://github.com/wework/speccy/blob/master/lib/server.js

[colinmollenhour]

This would be really handy, having to mix tools from Redocly and Swagger to get this functionality is a sub-par experience. My use-cases:

• Setup review apps in the project CI environment
• Support hot-reload for dev - allows me to use OAS features that Stoplight Studio doesn't support such as $ref anywhere - a pattern learned from Redocly

[schroedan]

Hello everyone, we from the skriptfabrik didn't want to wait any longer and have crafted our own Elements CLI. We published it today and hope that it is in the interest of Stoplight and the community and that it will be accepted by all. The documentation is still a bit poor. We would be happy if we can count on your support. Here are the key features in a nutshell:

• export as stand-alone HTML version with configurable web component
• preview via HTTP server + CORS proxy + livereload/watcher
• Elements CLI as NPM package
• Elements CLI as Docker image

Please check it out and feel free to give us feedback or create issues on GitHub.

Cheers!

[philsturgeon]

@schroedan brilliant work, thanks for contributing this. It’s what open-source is all about! 🙌🏻