# 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](/assets/screenshot-2024-09-11-at-15.47.35.7804d113b12048a08528ae61a5622c8645b870b715be71471a5da741e8b03c53.9c1bb791.png) * Broken links in locale folders when a file is generated as a plugin output. [Source](https://creativara.apishowdown.com/summary-training18#the-bad) * 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](/assets/workflow-guide-server-error.454ff579d28b718fd8864ee4244cc2d7fa369e4c54aedd4dba394395d1b1ebde.9c1bb791.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](https://innovario.apishowdown.com/debrief/project-18#what-did-you-find-confusing) * 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: ```txt 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) ```txt 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](https://idearium.apishowdown.com/debriefs/training-18-debrief#what-did-you-find-confusing) * 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" ```txt --- 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](https://innovique.apishowdown.com/week18). * 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.