search

opticdev / optic

OpenAPI linting, diffing and testing. Optic helps prevent breaking changes, publish accurate documentation and improve the design of your APIs.
https://useoptic.com
MIT License
1.36k stars 83 forks source link

Allow to print weblink (instead of openning it) and change host address #2854

Closed ouvreboite closed 2 weeks ago

ouvreboite commented 2 months ago

Context

First, congratulation on your integration with Atlassian 👏

I see in the latest release (1.0) and commits that any links to the Optic SaaS is getting removed, making the CLI a pure standalone. It's unclear to me if this is a "last stand" (meaning optic support will mostly end) or a new beginning 🙏 .

If support will actively continue, I would like to propose some further improvement to the --web experience.

Thanks to https://github.com/opticdev/optic/commit/2e235abff177bcbf1bd2ce089c2e79af500727cc the webapp code is now bundled and distributed. This allow to run locally a diff and see the result in the browser by running the webapp from the local node_modules.

That's nice for manual usage, but I'm interested in storing the link (as part of a commit or review) for other people to be able to open it.

That's not possible currently:

As self-hosting the webapp is now possible (extract the build folder from the node_modules and expose it with a basic webserver), what is missing is a way to print the link and change the base path to target a self-hosted instance.

Describe the enhancement

  1. Add a new diff --weblink option that returns (only) the link, instead of opening it.
  2. Add a new diff --webhost=https://my-host.domain.com option, that change the protocol and host of the generated link for both --web and --weblink

Example of usage

$ optic diff oas.yaml --weblink --webhost http://my-host.domain.com
https://my-host.domain.com#Wy4IQRQlc9MAnAWOa15cEr/5E0...

Additional information If you are open to contributions, I could work on it.

acunniffe commented 2 months ago

Thanks @ouvreboite! We've moved all the Cloud pieces of Optic into Atlassian Compass , so for now all the dashboards, visualizations, hosted history, etc is being developed there. The CLI + diffing capabilities are going to be an open source project now and we'll try to keep up with patches + issues.

I like the idea of self-hosting the --web view, but one thing to note is that since it uses the URL fragment, and the diffs can be quite long (~1mb for very large specs), not every browser will let you open them by clicking on a link. We got around this by using the native open url functionality supported by most terminals which effectively bypasses those limits.

So the server you host might need to do more than just serve the HTML page. It might need to store and retrieve diffs based on some ID scheme.

If your diffs are on the smaller side, just hosting the HTML might work.

Feel free to open any PRs you want and we'll take a look!