Skip to content

Commit 464e294

Browse files
CoderrobCoderrob
committed
feat: initial raml api definition widget
1 parent 8e8d8b2 commit 464e294

17 files changed

+17742
-3
lines changed

‎.editorconfig‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# EditorConfig is awesome: https://EditorConfig.org
2+
3+
# top-most EditorConfig file
4+
root = true
5+
6+
# Unix-style newlines with a newline ending every file
7+
[*]
8+
end_of_line = lf
9+
insert_final_newline = true
10+
charset = utf-8
11+
indent_style = space
12+
indent_size = 2

‎.eslintrc.js‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
2+
const path = require('path');
3+
4+
module.exports = {
5+
root: true,
6+
plugins: ['@spotify', 'react', 'testing-library'],
7+
ignorePatterns: ['.eslintrc.js', '.eslintrc.cjs'],
8+
rules: {},
9+
overrides: [
10+
{
11+
files: ['**/*.[jt]s?(x)'],
12+
excludedFiles: '**/*.{test,spec}.[jt]s?(x)',
13+
rules: {
14+
'react/forbid-elements': [
15+
1,
16+
{
17+
forbid: [
18+
{
19+
element: 'button',
20+
message: 'use Material UI <Button> instead',
21+
},
22+
{ element: 'p', message: 'use Material UI <Typography> instead' },
23+
{
24+
element: 'span',
25+
message: 'use a Material UI <Typography> variant instead',
26+
},
27+
],
28+
},
29+
],
30+
},
31+
},
32+
],
33+
};

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,12 @@ dist
134134
.yarn/build-state.yml
135135
.yarn/install-state.gz
136136
.pnp.*
137+
138+
# Mac junk
139+
.DS_Store
140+
141+
# BS config
142+
*.local.yaml
143+
144+
# TS compiled types
145+
dist-types

‎.prettierignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dist
2+
dist-types
3+
coverage
4+
.vscode
5+
.eslintrc.js

‎CHANGELOG.md‎

Whitespace-only changes.

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@
186186
same "printed page" as the copyright notice for easier
187187
identification within third-party archives.
188188

189-
Copyright [yyyy] [name of copyright owner]
189+
Copyright 2025 Robert Lindley
190190

191191
Licensed under the Apache License, Version 2.0 (the "License");
192192
you may not use this file except in compliance with the License.

‎README.md‎

Lines changed: 118 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,118 @@
1-
# plugin-api-docs-module-raml-gen-doc
2-
Adds RAML to OpenAPI conversion support in Backstage API Docs for seamless rendering and integration.
1+
# Backstage.io Api-Docs Plugin: RAML to OpenAPI Renderer
2+
3+
## Overview
4+
5+
This is a plugin for [Backstage](https://backstage.io/) that extends the capabilities of the built-in API documentation feature by adding support for parsing and rendering [RAML](https://raml.org/) (RESTful API Modeling Language) definitions in [OpenAPI](https://www.openapis.org/) format.
6+
7+
With this integration, Backstage users can seamlessly view and manage their APIs defined in RAML within the same familiar interface as OpenAPI.
8+
9+
## Features
10+
11+
- **Converts RAML to OpenAPI**: Automatically translates RAML API definitions into OpenAPI v2.0 specifications.
12+
- **Enhanced Documentation**: Leverages Backstage's Api-Docs capabilities for a consistent user experience.
13+
- **Easy Integration**: Designed to work seamlessly with existing Backstage setups and plugins.
14+
15+
## Prerequisites
16+
17+
- Basic knowledge of Backstage setup.
18+
- Node.js installed on your development machine (preferably the latest LTS version).
19+
- Existing or planned RAML API definitions in your project.
20+
21+
## Installation
22+
23+
1. **Clone or Download this Repository**
24+
25+
```bash
26+
git clone https://github.com/Coderrob/plugin-api-docs-module-raml-gen-doc.git
27+
cd plugin-api-docs-module-raml-gen-doc
28+
```
29+
30+
2. **Install Dependencies**
31+
32+
Ensure that you have Backstage installed and configured. If not, follow the [official Backstage documentation](https://backstage.io/docs/getting-started/) to set up a new instance.
33+
34+
3. **Build the Plugin**
35+
36+
```bash
37+
yarn build
38+
```
39+
40+
4. **Link the Plugin to your Backstage App**
41+
42+
Navigate to your Backstage app directory and link the plugin:
43+
44+
```bash
45+
cd path/to/your-backstage-app
46+
yarn --cwd packages/app add @coderrob/plugin-api-docs-module-raml-gen-doc
47+
```
48+
49+
5. **Register the Plugin in Your App's `packages/app/src/plugins.ts`**
50+
51+
Add the following import statement to register the plugin with Backstage:
52+
53+
```typescript
54+
export const ramlOpenApiPlugin = createPlugin({
55+
id: 'raml-open-api',
56+
routes: {
57+
root: rootRouteRef,
58+
},
59+
});
60+
```
61+
62+
6. **Restart Your Backstage App**
63+
64+
After making changes, restart your Backstage application to see the new plugin in action:
65+
66+
```bash
67+
yarn dev
68+
```
69+
70+
## Usage
71+
72+
1. **Add RAML Files**
73+
74+
Place your RAML API definitions under a directory specified for API documentation within your Backstage app (e.g., `static/docs/api`).
75+
76+
2. **Navigate to API Docs**
77+
78+
Access the API documentation section in Backstage, and you should see an option or tab dedicated to RAML-based APIs.
79+
80+
3. **View Rendered OpenAPI Documentation**
81+
82+
The plugin will automatically convert the RAML definitions into OpenAPI format and render them using Backstage's built-in tools for a clean, interactive experience.
83+
84+
## Configuration
85+
86+
The plugin leverages Backstage’s existing configuration settings for API documentation. No additional configuration is required unless you need to customize the conversion process or rendering options.
87+
88+
If customization is needed, refer to the following optional configuration steps:
89+
90+
1. **Custom Conversion Scripts**
91+
92+
Modify the conversion scripts located in `src/raml-to-openapi` to suit your specific RAML and OpenAPI version requirements.
93+
94+
2. **Update Plugin Settings**
95+
96+
Adjust settings within `src/plugin.tsx` or related configuration files to change behavior such as API scanning paths, default rendering themes, etc.
97+
98+
## Contributing
99+
100+
Contributions are welcome! Feel free to open issues for bug reports or feature requests, and submit pull requests with your enhancements.
101+
102+
- Fork this repository.
103+
- Create a new branch: `git checkout -b feature/your-feature-name`.
104+
- Commit your changes: `git commit -m "Add some feature"`.
105+
- Push to the branch: `git push origin feature/your-feature-name`.
106+
- Open a pull request against the main branch in this repository.
107+
108+
## License
109+
110+
This plugin is released under the Apache 2.0 License. Please see [LICENSE](LICENSE) for more details.
111+
112+
## Support and Community
113+
114+
For any questions or support related to this plugin, please join our community on Slack or check out the GitHub Issues section of this repository.
115+
116+
- **GitHub Issues**: [Issues on GitHub](https://github.com/your-repo/backstage-raml-openapi-plugin/issues)
117+
118+
Enjoy using this plugin to enhance your Backstage API documentation capabilities with RAML support!

‎backstage.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"version": "1.38.1"
3+
}

‎package.json‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"author": "Robert (Coderrob) Lindley",
3+
"backstage": {
4+
"role": "frontend-plugin"
5+
},
6+
"bugs": "https://github.com/Coderrob/plugin-api-docs-module-raml-gen-doc/issues",
7+
"dependencies": {
8+
"@backstage/core-components": "^0.17.2",
9+
"@backstage/plugin-api-docs": "^0.12.7",
10+
"webapi-parser": "^0.5.0"
11+
},
12+
"description": "This is a plugin for Backstage.IO that extends the capabilities of the built-in Api Docs feature by adding support for parsing and rendering RAML (RESTful API Modeling Language) definitions in OpenAPI format.",
13+
"devDependencies": {
14+
"@backstage/cli": "^0.32.0",
15+
"@backstage/dev-utils": "^1.1.9",
16+
"@backstage/test-utils": "^1.7.7",
17+
"@spotify/eslint-config": "^15.0.0",
18+
"@testing-library/jest-dom": "6.6.3",
19+
"@testing-library/react": "14.3.1",
20+
"@testing-library/react-hooks": "8.0.1",
21+
"@testing-library/user-event": "14.6.1",
22+
"eslint": "^9.28.0",
23+
"eslint-plugin-testing-library": "^7.4.0",
24+
"msw": "1.3.5",
25+
"react": "^18",
26+
"react-dom": "^18",
27+
"react-router-dom": "^6"
28+
},
29+
"exports": {
30+
".": "./src/index.ts",
31+
"./package.json": "./package.json"
32+
},
33+
"files": [
34+
"dist"
35+
],
36+
"keywords": [
37+
"backstage",
38+
"plugin",
39+
"api-docs",
40+
"raml"
41+
],
42+
"license": "Apache-2.0",
43+
"main": "src/index.ts",
44+
"name": "@coderrob/plugin-api-docs-module-raml-gen-doc",
45+
"packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
46+
"peerDependencies": {
47+
"react": "^16 || ^17 || ^18"
48+
},
49+
"publishConfig": {
50+
"access": "public"
51+
},
52+
"repository": {
53+
"type": "git",
54+
"url": "https://github.com/Coderrob/plugin-api-docs-module-raml-gen-doc"
55+
},
56+
"scripts": {
57+
"build": "backstage-cli package build",
58+
"clean": "backstage-cli package clean",
59+
"lint": "backstage-cli package lint",
60+
"postpack": "backstage-cli package postpack",
61+
"prepack": "backstage-cli package prepack",
62+
"start": "backstage-cli package start",
63+
"test": "backstage-cli package test --passWithNoTests --coverage",
64+
"tsc": "tsc"
65+
},
66+
"sideEffects": false,
67+
"types": "src/index.ts",
68+
"typesVersions": {
69+
"*": {
70+
"package.json": [
71+
"package.json"
72+
]
73+
}
74+
},
75+
"version": "0.0.1"
76+
}

‎src/addRamlDefinitionWidget.tsx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import { ApiDefinitionWidget } from "@backstage/plugin-api-docs";
2+
import RamlDefinitionWidget from "./components/RamlDefinitionWidget";
3+
import {
4+
OPENAPI_WIDGET_TYPE,
5+
RAML_WIDGET_TITLE,
6+
RAML_WIDGET_TYPE,
7+
} from "./constants";
8+
9+
/**
10+
* Backstage Api Definition Widget array filter by definition type.
11+
* @param type the api definition widget type (e.g: openapi, raml)
12+
* @returns
13+
*/
14+
function byType(type: string) {
15+
return (widget: ApiDefinitionWidget) => widget.type === type;
16+
}
17+
18+
/**
19+
* Adds the RAML Api Definition Widget to the list
20+
* of widgets. The widget will only be added if the
21+
* OpenApi widget is present in the list of widgets.
22+
*
23+
* The RAML definition is parsed to OpenApi 2.0 spec
24+
* and passed through the OpenApi Api Definition Widget
25+
* for rendering in Api Docs.
26+
* @param widgets the default or custom widgets
27+
* @returns the widgets with the raml widget added if
28+
* the openapi widget was available.
29+
*/
30+
export function addRamlDefinitionWidget(
31+
widgets: ApiDefinitionWidget[]
32+
): ApiDefinitionWidget[] {
33+
if (!Array.isArray(widgets)) {
34+
return [];
35+
}
36+
37+
/**
38+
* Find the OpenApi widget if its available
39+
*/
40+
const openapiWidget = widgets.find(byType(OPENAPI_WIDGET_TYPE));
41+
42+
/**
43+
* If the OpenApi widget is not available
44+
* we can't wrap it to render the RAML.
45+
*/
46+
if (!openapiWidget) {
47+
return widgets;
48+
}
49+
50+
/**
51+
* Add the RAML Api Definition widget using the
52+
* OpenApi widget to handle the parsed RAML.
53+
*/
54+
return widgets.concat({
55+
type: RAML_WIDGET_TYPE,
56+
title: RAML_WIDGET_TITLE,
57+
component: (definition: string) => (
58+
<RamlDefinitionWidget
59+
component={openapiWidget?.component}
60+
definition={definition}
61+
/>
62+
),
63+
});
64+
}

0 commit comments

Comments
 (0)