* #1391: add generated doc cleaning script
## What
The cleaning script replaces all references to the Unleash ushosted instance in the
generated OpenAPI docs. It removes extra path segments (such as leading
`/ushosted` instances) and replaces the ushosted base url with something
user-agnostic.
## Why
When we host the OpenAPI docs in our official documentation, the generated
docs shouldn't necessarily point at _one specific instance_, and especially
not one that the reader is unlikely to ever use. Instead, we can remove all
the bits that are specific to the generation source we use, and make the docs
easier to use. In particular, removing the leading `/ushosted` is likely to
save us loooots of questions.
* #1391: change env var used for generating openapi from localhost
Using NODE_ENV=development doesn't necessarily make sense, so adding
an extra variable sounds reasonable to me.
* #1391: ensure that all generation commands also clean docs
* #1391: change <your-unleash-instance-url> to <your-unleash-url>
* #1391: fix ushosted replacement: not all paths start with /api
* #1391: chore: remove potential `ushosted` ending of api url
In the event that we change the base URL of OpenAPI, so that paths
don't start with `/ushosted/`, the script should still work, changing
those paths into <your-unleash-url> too.
Additionally, remove all instances of `/ushosted` that we find. In the
event that some things switch around or whatever.
## What
This PR (finally 🎉) adds generated OpenAPI docs to the official Unleash documentation. In addition to generating docs when things get merged to main, it also pushes new doc updates every day at 12:00 AM (cron `@daily`).
## Why
Now that we have OpenAPI'd all the things, we can finally start using it. This will allow us to remove hand-written api docs from the documentation and should make sure everything is always kept up to date.
### Generating from us-hosted (Unleash enterprise)
Unleash has several different versions (open source, pro, enterprise). The versions do not necessarily have the exact same api surface. In fact, the enterprise version has a few endpoints that open source does not.
Because we want to have _all_ endpoints listed in the documentation we need to generated the docs from an enterprise spec. Which brings us into the next point:
### The need for scheduled jobs
Regarding the daily scheduled tasks to update the documentation: why do we need that?
The docs are generated from the tip of the main branch. For most of the docs, this is good and something that we want. However, because the OpenAPI docs are generated from the enterprise edition, it _will not be in sync_ with the open source main branch.
Also, we probably do not want the docs to list the current bleeding edge api changes. Instead, we should prefer to use the latest enterprise release (roughly). However, because we don't get notified when this version is released and deployed, we'll instead run the API generation on a daily cadence.
This isn't the perfect solution, but it's simple and gets us 80% of the way there. More intricate solutions can be set up later.
## How
- By adding a scheduled workflow to the generate docs config.
- By adding .gitignore entries for the generated files
There's also some minor changes in styling etc.
## Dependencies
This is dependent on the changes introduced in #2062 having propagated to the enterprise release, which will probably not be for another week or so.
## Discussion
What should the API reference docs url be? I've set it to be `/reference/api/unleash/*` for now, but I'm on the fence about whether it should be `apis` or `api` in there. I also want to get the proxy and other APIs in there as we grow.
-------
## Commits
* docs: style openapi operation buttons
* docs: minor operation badge adjustments
* docs: use permalink to css snippet i copied
* docs: ignore files related to openapi generation
* docs: re-enable openapi docs
* Docs(#1391): prep for integration
* docs(#1391): run docs generation daily
* docs(#1391): add generation step to doc prs too
* docs(#1391): use the US hosted instance to generate docs
* docs(#1391): move doc generation into build command
* docs(#1391): use `/reference/api/*` instead of `/reference/apis/*`
The doc link appears to have pointed at an address that is no longer reachable. Instead, let's point to the equivalent GitHub link
Relates to and closes#2047
## What
This PR fixes some broken links that have been hanging around in the
docs for what seems like a very long time.
## Why
As discovered by the link check in #1912, there are a fair few broken
links in the docs. Everyone hates broken links because it makes it
harder to understand what they were supposed to be pointing at.
## How
There are 3 types of links that have been fixed:
- Links that should have been internal but were absolute. E.g.
`https://docs.getunleash.io/path/article` that should have been
`./article.md`
- External links that have changed, such as Slack's API description
- GitHub links to files that either no longer exist or that have been
moved. These links generally pointed to `master`/`main`, meaning
they are subject to change. They have been replaced with permalinks
pointing to specific commits.
-----
* docs: fix slack api doc link
* docs: update links in migration guide
* docs: fix broken link to ancient feature schema validation
* docs: update links to v3 auth hooks
* docs: update broken link in the go sdk article
* Fix: use permalink for GitHub link
* docs: fix wrong google auth link
* Docs: start experimenting with OpenAPI and docusaurus
* Docs: add docusaurus-theme-openapi-docs pkg
* Wip: current status
* Docs: Add 'docusaurus-plugin-api-docs'
* Move openapi into own sidebar; generate from localhost
* Chore: Update docusaurus plugin for OpenAPI
* Add website/yarn.lock to git
* Fix: fix CSS warning by using flex-end instead of end
* docs: make openapi generated code work again
* docs: make tags work properly with openapi sidebar
* Docs/chore: update OpenAPI tag scheme.
Add a whole bunch of new tags to make it easier to understand
available tags in OpenAPI.
* docs: point to new openapi docs from old api docs
* docs: typo
* Docs: link restructure
* docs: add operation indicators to openapi docs
* docs: change badge color for operations
* docs: update openapi-docs package
It now sorts tags the same as the schema
* docs: pluralize APIs in slug
* docs: update links to generated api docs
* docs: update openapi snapshot tests with new tags
* docs: conditionally load spec from localhost or from file
* docs: Remove changes relating to immediate switchover
* refactor: rename types; extract into separate file
* docs: fix api doc links
* Docs: Update compatibility matrix for php
* Docs: Update php compatibility table to include IP CIDR syntax
* Docs: Update impression data documentation
* Docs: Mention JavaScript proxy clients in impression data support
* Docs: add how-to enable the openapi spec
* Docs: fix and format how to run unleash proxy
* Fix: add backticks instead of single quotes
* Docs: remove unnecessary imports, format
* Docs: fix minor errors and update location section
* Implement user grouping feature for permissions
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Jaanus Sellin <sellinjaanus@gmail.com>
Co-authored-by: Nuno Góis <github@nunogois.com>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
