Skip to content
/
Training 18 Summary of de...
Last updated

Training 18 Summary of debriefs

The good

  • It was realy easy to get started with.
  • Easy to add new markdoc tag
  • Easy to navigate on OpenAPI description using sidebar
  • I liked the ability to reference OpenAPI operations using markdoc tags
  • Preview builds were fast
  • Code samples work out of the box from the instruction.
  • We liked the replay-openapi Markdoc tag.
  • The guide that was included with the assignment was very good and showed us how to build a new component and tag. We liked being able to get started so quickly.
  • The mock server is available on localhost to other tools.
  • The Markdoc openapi-code-sample and replay-openapi components are incredibly useful for this purpose!

The bad

  • It's hard to read hints in the online editor if they appear on the top lines. Also, the right side could be hidden. Screenshot 2024-09-11 at 15.47.35.png
  • Broken links in locale folders when a file is generated as a plugin output. Source
  • Sidebar broken links are not reported in WYSIWYG.
  • Having previous big APIs making the user experience worse: longer build time, etc.... We ignored them in the codebase.
  • The validation of product config override is invalid.
  • It isn't real clear why our stuff isn't working. It indicated there were problems, but n!ot clear instructions for fixing it. Not clear why there is a problem. Also, webview keeps timing out and having server issues. Workflow guide server error.png
  • Would be good to note that styled-components, react are available out of the box with realm
  • openapi-code-sample does not prefill operationId (it is required)
  • import errors in tsx files
  • Would be good to have autocomplete for md templates
  • In 0.98.2 relative path for logo image does not work (worked in 0.93.0) Source
  • It was hard to find an error between deprecation warnings
  • There was no error when editing project directly on main branch
  • Issues with realm in version 0.99 - project not starting due to image files resolve problem. Similar problem, but a bit different output: https://redoc-ly.slack.com/archives/C071H03PDC1/p1726050401168119 - in our case it was white screen with error.
  • After pasting SideBySide.tsx code, we have seen following error to all imports:
Cannot find module 'styled-components'. Did you mean to set the 'moduleResolution' option to 'nodenext', or to add aliases to the 'paths' option?(2792)

  • We couldn't find how to change/set title of code fence in our step by step guide

  • Horizontal lines and vertical lines have different color and we didn't find a way how to use the same color

  • We've had to full-restart Webview few times when making some changes to get them reflected.

  • There is this weird imports error that keeps appearing and disappearing in the editor (not sure why it changes all the time)

    Cannot find module '@redocly/theme/components/Markdown/Markdown'. Did you mean to set the 'moduleResolution' option to 'nodenext', or to add aliases to the 'paths' option?(2792)

  • The mock server doesn't work for the replay-openapi tag (we had to add the mock server URL manually). Source

  • You cannot delete a variable in replay-openapi. The save option is disabled if you clear the input. exampleKey updates the body but not the label for "Pick an example" option.

  • We were unable to move this guide inside museum v1 (the file isn't openable on click).

  • We had to install @redocly/theme to run it locally (though it works on Reunite without this package).

  • Additional error locally: ✘ [ERROR] Could not resolve "/Users/@theme/Templates/SideBySide.tsx"

    ---
template: './@theme/Templates/SideBySide.tsx'
---

    The correct path should be: "/Users/yaroslav/Redocly/idearium/@theme/Templates/SideBySide.tsx".

  • Cannot find module 'styled-components' or its corresponding type declarations. Should we install it?

  • "Mock server error. Could not generate response. No supported media type found in definition."

  • When we use some new dependencies in our files (ts, tsx), it would be nice to have some "install" or "add" button which adds this dependency in package.json

  • JavaScript heap out of memory error

  • Renaming folder in file tree keeps the old folder. Openapi specification structure dissapears from file tree after some time.

  • The mock server isn't available in the replay-openapi component, so it was difficult to show a working example in the guide.

  • We weren't able to add new environments to the mock server in the replay-openapi tag. We did a little hack where we added the path to the mock server as an additional server in the Museum API itself.

  • The replay-openapi tag doesn't allow setting requestBody parameters (or we couldn't figure out how to do that).

  • The auth types list cannot be scrolled, the box is chopped off at the bottom and you have to scroll some subtle intermediate pane that it is part of Source.

  • Writing anything in editor is super slow, I see letters 1-2 seconds after typing them

  • It seems like SideBySide.tsx doesn`t affect page at all, we tried different imports and tried to remove it.

  • Links in Markdown are not automatically linked.

  • The template doesn't work with absolute paths.

  • Incorrect templates are not reported.

  • There's strange behavior with front-matter when there are indentation issues.

  • If you open the webview in another window, the one in the app doesn't update.

  • Specifying an incorrect template path causes the webview to keep reloading indefinitely, eventually resulting in an error that does not describe the problem.

Suggestions

  • When we create a package.json it would be nice to have some boilerplate inside of it, now it's empty and you need to jump into npm documentation to find what should be there.
    💡 Idea: add also our realm (or another product) and start script.
  • Will be awesome to have context menu when you click to part of the definition. Inside context menu we can have:
    • copy operationId/copy description for operation
    • copy schema reference for schema
    • copy email for info->contact
  • Will be nice to have autocomplete for importing template file inside md frontmatter and prediction keys for frontmatter like template etc.
  • We would love to be able to paste request snippet/example as from our OAD pages into step by step guide
  • It would be great to have some built-in step by step guide component so we won't have to copy&paste components code
  • It would be great to have tutorial in our docs about step by step guides so it would be possible to search our documentation to find it
  • We had a typo in a folder name, but the webview errors weren't helpful at all for us to find why our code doesn't work. It could at least somehow highlight the 'broken' path.
  • It would be helpful to have a built-in code walkthrough with the ability to pass variables from previous steps, similar to how it's implemented in Postman via the "Tests" tab.
  • We have a protected API, but there's no way to register to get a username and password. We should add a registration endpoint, similar to what the Petstore API has, or remove the protection like the Train API did.
  • The listSpecialEvents endpoint should return separate events for each day. After that, we can remove the ticketDate parameter from the buyMuseumTickets endpoint.
  • Would be nice to copy operation id from tree. Now comand+c returns []!
  • In legacy portal there was a step-by-step guide implementation which allowed to use values from responses in subsequent steps. Wondering if this could be also implemented in Realm ?
  • Improve instructions:
    • SideBySide.tsx filename vs. StepByStepLayout component name
    • create Split component in separate file Split.tsx and import/export in components.tsx
    • it would be good to see some explanation how to schema.ts resolves components and where they all should be placed especially if you are working with multiple React components.
    • There's a mention about the replay-openapi tag. It would be good to see a link to documentation about it.
Previous page
Next page