Improve types, doc, allow spec on ApiSchema, fix showExample #339

serut · 2024-03-08T13:56:05Z

I wanted to add the ability to pass the spec param to ApiSchema, I end up with so many changes !!

There is still some FIXME on the code, I let you review and tell me what you think about it

changeset-bot · 2024-03-08T13:56:09Z

⚠️ No Changeset found

Latest commit: 438de62

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2024-03-08T13:56:09Z

Someone is attempting to deploy a commit to a Personal Account owned by @rohit-gohri on Vercel.

@rohit-gohri first needs to authorize it.

vercel · 2024-03-08T14:10:48Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
redocusaurus	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 17, 2024 8:38pm

rohit-gohri · 2024-03-08T14:13:42Z

I like the idea, correct me if I'm wrong but you want to avoid having to add the specs into the configuration and instead want to treat the spec as a doc?

serut · 2024-03-08T14:16:02Z

Yes, I cannot use the global configuration of redocusaurus as my specs are versionned. On every version of our software, we have the previous and the new spec inside the doc

rohit-gohri · 2024-03-08T15:29:27Z

Makes sense, what do you think about the idea of adding similar version commands as docs plugin and auto loading all yamls from an openapi folder with the name as ids?

There is some amount of preprocessing that needs to be done on the specs, so directly importing might work for you but not others

serut · 2024-03-08T17:34:15Z

When you speak about preprocessing spec files, you think about several spec files to merge ? I don't know every use case available.

Managing versionned spec files + preprocessing can be quite hard to do, like how do you know which spec file you need to use with the provided ID ? You will have, for one ID, several specs files, one for each version of the website.

In my project, we create some new microservice sometimes, so spec file can be unavailable for older version (or newer version if we remove a microservice)

serut · 2024-03-08T17:36:39Z

packages/docusaurus-theme-redoc/src/types/common.ts

+export type RedocProps = SpecProps & {
+  /**
+   * FIXME - incorrect name - should be isExternalUrl
+   */
+  isSpecFile?: boolean;
+  className?: string;
+  optionsOverrides?: RedocRawOptions;
+  /**
+   * External URL to load spec file from
+   * FIXME - incorrect name - should be externalUrl
+   */
+  url?: string;
+};


need your review. I think isSpecFile can be removed now since I've added a tester that check if the user provided an url starting with http

Other point: When you provide url to Redoc, it means you want to render an external swagger link. It should be renamed... (or at least documented)

I think isSpecFile can be removed now since I've added a tester that check if the user provided an url starting with http

It could also be a relative url to a yaml file in the static directory.

When you provide url to Redoc, it means you want to render an external swagger link. It should be renamed... (or at least documented)

Currently it works as the download url as the processed one removes some formatting which makes it hard to read

The external url is not intended, will see if the 2 usecases can be separated

Feel free to commit over my PR or tell me what to do.

This is weak part of this MR

It could also be a relative url to a yaml file in the static directory.

Yes, I've made a function that computes if the file is inside the doc or on another website. That's just checking if the URL start with http, no need to ask something as a config attribute

rohit-gohri · 2024-03-08T18:14:01Z

like how do you know which spec file you need to use with the provided ID ? You will have, for one ID, several specs files, one for each version of the website.

I was thinking the same way markdown files are versioned, load files and auto generate ids for them based on path. But I think your approach should also be supported, it makes sense since we are exposing components that can be used in Mdx.

I'll create a separate issue for versioning ( EDIT: created - #341 ), I have an idea, will tag you when a PR is ready and you can see if it would work for you

package.json

packages/docusaurus-theme-redoc/src/theme/ApiSchema/ApiSchema.tsx

packages/docusaurus-theme-redoc/src/utils/useSpec.ts

packages/docusaurus-theme-redoc/src/types/common.ts

rohit-gohri · 2024-03-08T18:34:34Z

@serut Depending on how much time you have, you can try to make it backward compatible; or can also just let it be, and in that case I'll cherry pick the relevant changes in a separate PR and add you as a co-author.

Thanks for opening the PR, I really like the idea of being able to just import openapi docs in Mdx without any configuration

serut · 2024-03-09T14:09:56Z

So far so great, everything looks backward compatible, and types are easier to maintain.

I let you review this MR

serut · 2024-03-15T11:31:12Z

Did you had time to review this merge request @rohit-gohri ?

rohit-gohri

Hey Sorry for the late review, but there are still a few breaking changes and some props that don't work everywhere. If you are okay with it, I can merge it but I'll have to make some changes before releasing? What do you think?

rohit-gohri · 2024-03-24T11:55:21Z

packages/docusaurus-plugin-redoc/src/index.ts

@@ -33,6 +33,10 @@ const version = require('../package.json').version;

 export { PluginOptions, PluginDirectUsageOptions, loadRedoclyConfig };

+function getIsExternalUrl(url = '') {


this still doesn't handle relative urls

Do you really want to handle relative URL (inside the doc) as external API ?

I don't get the usecase.

Either you use RedocStandalone if the schema is outside of the doc, either you use the real Redoc and it handles it by loading it

It supports it currently, so gotta keep it

Oh... I didn't think it was intented.

It's more a miss-usage of the API

packages/docusaurus-theme-redoc/src/theme/ApiSchema/ApiSchema.tsx

rohit-gohri · 2024-03-24T11:58:19Z

packages/docusaurus-theme-redoc/src/theme/Redoc/Redoc.tsx


-  if ((isDevMode && isSpecFile === false) || !spec) {
+  if (getIsExternalUrl(url)) {


This is not what we want, external urls should still be parsed at build time for server side rendering

Ok, maybe I miss the usecase... What is the difference between running in client mode and server side rendering mode for props in this component ?

The difference is if the html is generated at build time (and hence works for SEO and works without javascript) or on client side

Yes but in terms of props, what's the difference ?

packages/docusaurus-theme-redoc/src/theme/useSpec/index.ts

packages/docusaurus-theme-redoc/src/theme/useSpecData/useSpecData.ts

rohit-gohri · 2024-03-24T12:03:01Z

packages/docusaurus-theme-redoc/src/types/modules.ts

+  lightThemeOptions: import('redoc/typings').RedocRawOptions;
+}
+
+type RedocProps = SpecProps & {


this is what I was talking about here - https://github.com/rohit-gohri/redocusaurus/pull/339/files#r1518118853

The id is now available as a prop in RedocProps also though SpecProps. But it doesn't work

Hmm strange, when I run the website it looks ok.

But I can be wrong as every OpenAPI example in the website contains approximative content. We should make many OpenAPI example and replace Dog, Cat ... with new animals (Elephant...) to be sure the right OpenAPI is loaded

It looks okay, but this compnent now has props which don't do anything

Are you sure it's not working with id ? Everything is given to useSpec so it should works

Should be added there in that case https://github.com/rohit-gohri/redocusaurus/pull/339/files#diff-28d0aac1a088788b029652a42c7bfb38079857218f6f9f29be02cf9dff768a2cR43

serut · 2024-03-24T12:52:00Z

You can merge it on another branch than master to do some work on it easier (if you cannot push commit on my fork).

Or merge it on master, as you want

vercel bot had a problem deploying to Preview March 8, 2024 14:12 Failure

serut commented Mar 8, 2024

View reviewed changes

rohit-gohri reviewed Mar 8, 2024

View reviewed changes

rohit-gohri mentioned this pull request Mar 8, 2024

Support versioning API along with docs #341

Open

serut added 2 commits March 9, 2024 12:27

Improve types, doc, allow spec on ApiSchema, fix showExample

1784940

No more export default + fix typings

438de62

serut force-pushed the feature/various-improvements branch from acd3732 to 438de62 Compare March 9, 2024 14:05

rohit-gohri self-requested a review March 17, 2024 20:36

vercel bot deployed to Preview March 17, 2024 20:38 View deployment

rohit-gohri reviewed Mar 24, 2024

View reviewed changes

rohit-gohri changed the base branch from main to feature/pass-spec-directly March 24, 2024 22:24

rohit-gohri merged commit 162cdc6 into rohit-gohri:feature/pass-spec-directly Mar 24, 2024
3 of 5 checks passed

rohit-gohri mentioned this pull request Mar 24, 2024

Allow passing spec directly to various components #347

Draft

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve types, doc, allow spec on ApiSchema, fix showExample #339

Improve types, doc, allow spec on ApiSchema, fix showExample #339

serut commented Mar 8, 2024

changeset-bot bot commented Mar 8, 2024 •

edited

Loading

vercel bot commented Mar 8, 2024

vercel bot commented Mar 8, 2024 •

edited

Loading

rohit-gohri commented Mar 8, 2024

serut commented Mar 8, 2024

rohit-gohri commented Mar 8, 2024

serut commented Mar 8, 2024

serut Mar 8, 2024

rohit-gohri Mar 8, 2024

serut Mar 8, 2024

serut Mar 8, 2024

rohit-gohri commented Mar 8, 2024 •

edited

Loading

rohit-gohri commented Mar 8, 2024 •

edited

Loading

serut commented Mar 9, 2024

serut commented Mar 15, 2024

rohit-gohri left a comment

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

rohit-gohri Mar 24, 2024

serut Mar 24, 2024

serut commented Mar 24, 2024 •

edited

Loading

		@@ -33,6 +33,10 @@ const version = require('../package.json').version;

		export { PluginOptions, PluginDirectUsageOptions, loadRedoclyConfig };

		function getIsExternalUrl(url = '') {


		if ((isDevMode && isSpecFile === false) \|\| !spec) {
		if (getIsExternalUrl(url)) {

Improve types, doc, allow spec on ApiSchema, fix showExample #339

Improve types, doc, allow spec on ApiSchema, fix showExample #339

Conversation

serut commented Mar 8, 2024

changeset-bot bot commented Mar 8, 2024 • edited Loading

⚠️ No Changeset found

vercel bot commented Mar 8, 2024

vercel bot commented Mar 8, 2024 • edited Loading

rohit-gohri commented Mar 8, 2024

serut commented Mar 8, 2024

rohit-gohri commented Mar 8, 2024

serut commented Mar 8, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rohit-gohri commented Mar 8, 2024 • edited Loading

rohit-gohri commented Mar 8, 2024 • edited Loading

serut commented Mar 9, 2024

serut commented Mar 15, 2024

rohit-gohri left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serut commented Mar 24, 2024 • edited Loading

changeset-bot bot commented Mar 8, 2024 •

edited

Loading

vercel bot commented Mar 8, 2024 •

edited

Loading

rohit-gohri commented Mar 8, 2024 •

edited

Loading

rohit-gohri commented Mar 8, 2024 •

edited

Loading

serut commented Mar 24, 2024 •

edited

Loading