Add a Prototype for API Documentations by dhenneke · Pull Request #1737 · backstage/backstage

dhenneke · 2020-07-24T14:52:33Z

Here is our first implementation for the API documentation plugin aka api-docs. See here for the initial discussion by @Fox32.

For now API entities can be added to the catalog and referenced from a component. They are then displayed under the API tab in the details view. In addition, a standalone API list is added. See the screenshots for some details:

We ran into some problems that are not solved till now. Probably these are things we can't resolve right now, but should be the next steps:

We added two external react components to display the documentation. Styling of these components could be improved by introducing own CSS files. Especially dark mode isn't supported right now. The question is, how can we style it using the backstage theme?
Right now it is difficult to add new plugins to the catalog details. We added it directly, but it feels like quite a hard dependency. In addition the tab navigation isn't ready yet, but others are struggeling too.
Adding a API list to the plugin would be nice, but brings some problems. We would have a cycling dependency between the plugin and the catalog-plugin (the scaffolder-plugin has the same problem). Do we need a package that contains central catalog components like the catalogAPiRef?
We added AsyncAPI support, but have trouble running the jest tests with it. It's not clear what exactly the error during test execution means: "Jest encountered an unexpected token"
An ownership property for the API entity might be interesting.

We know the PR is quite big but we think that it is a good start for discussions on a working prototype. If you are interested, we can split it up a bit more along the commits and contribute the changes in individual PRs.

stefanalund · 2020-07-24T20:19:04Z

Rockstars. Thanks a lot! 💯🥳👏🏼

Rugvip

Thank you! Stellar stuff 😁 🌟

High quality all around, super happy to merge and work out any specific details later.

Rugvip · 2020-07-24T15:12:02Z

It's silly, but best to return a cancel function here in case we get instantly unmounted :p

Rugvip · 2020-07-27T12:03:50Z

Happy to merge but no promises on keeping this 😅

It does look to me like there's opportunity for creating a pattern for how to define relationships to other entities. Maybe even a separate top-level object and a more list-style approach with room for metadata about the relationship. Or just something more simple like this. Totally not in scope of this PR though

Yes. Since ADR 005 also intends the "consumes" relation it might be good to have a more general approach in the future. As soon as some kind of versioning is introduced, this simple modeling will also not suffice. But we will see then.

Rugvip · 2020-07-27T15:53:08Z

jest.mock can be placed below the imports as well, so I'm wondering why you place it here? Asking because I'm considering switching to a faster build that doesn't support that hoisting and this would have to be done everywhere 😁

I copied it from the catalog plugin 😀. But I can change it.

Dammit, ok 😁

It's fine to leave as is

Rugvip · 2020-07-27T15:53:24Z

Rugvip · 2020-07-27T16:22:19Z

This definitely needs a nicer API (in core) imo, but not for this PR 😅

Rugvip · 2020-07-27T16:24:05Z

Tbh I'm not sure why the local isn't the only one. Let's re-evaluate after merging this :>

mbruggmann · 2020-07-28T07:09:36Z

Can't really comment on the TypeScript implementation, but from a modelling/metadata perspective this looks pretty great! As @Rugvip mentioned, we might want to give the spec.implementsApis part another thought but I'd vote to start with this for now and re-evaluate later if we need to. Thanks so much for getting this going!

dhenneke · 2020-07-28T10:41:07Z

I fixed the issue with the failing build by updating the jest config (see last commit):

- '/node_modules/(?!.*\\.(?:esm\\.js|bmp|gif|jpg|jpeg|png|frag|xml|svg)$)',
+ '/node_modules/(?!@kyma-project/asyncapi-react/)(?!.*\\.(?:esm\\.js|bmp|gif|jpg|jpeg|png|frag|xml|svg)$)',

The npm package seems to be a bit odd...

I am not sure if this is a smart solution, especially since I changed in the cli package :-/.

Rugvip · 2020-07-28T14:10:31Z

Yeah this is idd unfortunate. The package is using esm modules but really doesn't signal that in any way as far as I can tell. I don't wanna block this PR because of the issue so fine with override for now, but we do need to figure out a long-term solution. It would be possible to add this to .jest.transformIgnorePatterns inside package.json of the api-docs package, but that would have to be kept in sync with updates to this config so it isn't great either.

@Rugvip I can also try to fix the original package so we don't get an issue here. But tbh, I am not really deep into jest and esm modules. Do you have a clue what might be wrong there? Would you say this issue is specific to the configuration in the backstage repository?

It's a somewhat common override that's needed when using jest. The package is built in a way that makes it tricky to consume, and could definitely be left as feedback to the package author.

A common way to solve the issue is to build both CommonJS and ESModule outputs, and then point to each using main and module fields in package.json. It's puts more requirements on the build tooling though. For example, we do that here: https://github.com/spotify/backstage/blob/c4b6c1397577b89f117a2f663088315dda75aaa7/packages/catalog-model/package.json#L11

Fox32 · 2020-08-07T10:40:20Z

Just to let you know: we are still interested, but on vacation right now. We will continue with it next week 😊

Rugvip · 2020-08-07T11:27:56Z

@Fox32 thank you for the update! Many vacations on our side too 😁

stefanalund · 2020-08-12T07:04:01Z

@dhenneke what is the status of this PR? Excited to get it merged 😃

dhenneke · 2020-08-12T07:05:41Z

The build should work now. Strangely, the "Frontend CI" workflow has not been triggered so the tests weren't executed 😕. I wonder if it is connected to 9d1f531.

Apart from that: Are there any blockers before merging this PR? If our changes in the Entity-tab-behavior are conflicting, we will be happy to remove them in favor of the work done in #1835. We could integrate that separately after that has been merged. Just leave a short note on what is missing on the road of getting this merged.

Rugvip · 2020-08-12T08:41:47Z

@dhenneke Will have a proper look in a bit, but iirc we're just waiting for conflicts to be resolved and should then be good to merge 👍

Workflows are indeed not triggering correctly, fix in it's way 😅 #1918

Can't comment on the tab implementation, what do you think @hooloovooo ?

…ed apis per component

…y all implemented apis

…ark mode

dhenneke · 2020-08-13T08:33:58Z

@Rugvip did you have time to have a look?

Rugvip

!

CI failures are fixed in latest master, so you'll need to trigger a build on top of that

freben

This is really solid work. Thank you!

freben · 2020-08-13T09:55:50Z

+
+## Links
+
+- (The Backstage homepage)[https://backstage.io]


mixed up the square brackets and parentheses

Can fix later, let's 😁

dhenneke · 2020-08-13T10:27:09Z

Builds are green 😲

Fox32 · 2020-08-13T11:48:21Z

🥳

dhenneke requested a review from a team as a code owner July 24, 2020 14:52

Rugvip approved these changes Jul 27, 2020

View reviewed changes

dhenneke force-pushed the feat/api-catalog branch from cf4de4a to 51a23b8 Compare July 28, 2020 10:36

Rugvip reviewed Jul 28, 2020

View reviewed changes

dhenneke force-pushed the feat/api-catalog branch 3 times, most recently from b642972 to 91b9ece Compare August 12, 2020 06:36

dhenneke force-pushed the feat/api-catalog branch 4 times, most recently from 9fe12e7 to 1438d31 Compare August 12, 2020 11:15

dhenneke and others added 11 commits August 12, 2020 13:53

feat(catalog): add entity to describe APIs

b5f8aa8

feat(catalog): add field to the component entity to specify implement…

7c9e84b

…ed apis per component

chore(catalog): add script to add the example entities

f33c3db

feat(api-docs): add plugin that provides widgets that display api docs

812659c

feat(catalog): add trivial tab implementation and add a tab to displa…

9a23ea8

…y all implemented apis

feat(app): add api-docs plugin to the navigation

58f86f9

feat(api-docs): add routes to display all api entities

3534c08

feat(api-docs): render documentation of type asyncapi

5a023c3

fix(api-docs): improve the styling of the asyncapi documentation in d…

237595f

…ark mode

chore: update yarn.lock

bd68004

chore: fix jest rule to be able to the use the asyncapi-react module

bf76f07

dhenneke force-pushed the feat/api-catalog branch from 1438d31 to bf76f07 Compare August 12, 2020 12:01

Update @types/swagger-ui-react

f809238

Rugvip approved these changes Aug 13, 2020

View reviewed changes

Merge branch 'master' into feat/api-catalog

3566434

freben approved these changes Aug 13, 2020

View reviewed changes

abstrask mentioned this pull request Aug 13, 2020

Expose Capability documentation via TechDocs dfds/backstage_originaldfdsfork#57

Closed

6 tasks

Fox32 mentioned this pull request Aug 13, 2020

[Plugin] Service API documentation #627

Closed

Rugvip merged commit e0632bc into backstage:master Aug 13, 2020

dhenneke deleted the feat/api-catalog branch August 13, 2020 11:39

dhenneke mentioned this pull request Aug 13, 2020

feat(catalog): update trivial tab implementation #1945

Merged

This was referenced Aug 14, 2020

Add styling (especially dark mode) for the asyncAPI display component #1958

Merged

Improve styling of OpenAPI component (especially in dark mode) #1961

Merged

Rugvip mentioned this pull request Aug 14, 2020

[RFC] Entity Relations #1964

Closed

Uh oh!

Conversation

dhenneke commented Jul 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanalund commented Jul 24, 2020

Uh oh!

Rugvip left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mbruggmann commented Jul 28, 2020

Uh oh!

dhenneke commented Jul 28, 2020

Uh oh!

Rugvip Jul 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fox32 commented Aug 7, 2020

Uh oh!

Rugvip commented Aug 7, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanalund commented Aug 12, 2020

Uh oh!

dhenneke commented Aug 12, 2020

Uh oh!

Rugvip commented Aug 12, 2020

Uh oh!

dhenneke commented Aug 13, 2020

Uh oh!

Rugvip left a comment

Choose a reason for hiding this comment

Uh oh!

freben left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dhenneke commented Aug 13, 2020

Uh oh!

Fox32 commented Aug 13, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dhenneke commented Jul 24, 2020 •

edited

Loading

Rugvip Jul 28, 2020 •

edited

Loading

Rugvip commented Aug 7, 2020 •

edited

Loading