Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/charlyjazz/prettyrestdoc
A chrome extension and also a web app. Swagger UI Alternative. Get a pretty rest documentation app easily cloning this stuff :book:
https://github.com/charlyjazz/prettyrestdoc
api-documentation-tool browser-extension chrome-extension css documentation extension html react rest rest-api rest-documentation swagger swagger-ui
Last synced: 2 months ago
JSON representation
A chrome extension and also a web app. Swagger UI Alternative. Get a pretty rest documentation app easily cloning this stuff :book:
- Host: GitHub
- URL: https://github.com/charlyjazz/prettyrestdoc
- Owner: CharlyJazz
- License: apache-2.0
- Created: 2021-06-30T18:26:03.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-15T22:24:24.000Z (6 months ago)
- Last Synced: 2024-08-16T02:33:21.362Z (6 months ago)
- Topics: api-documentation-tool, browser-extension, chrome-extension, css, documentation, extension, html, react, rest, rest-api, rest-documentation, swagger, swagger-ui
- Language: TypeScript
- Homepage: https://chrome.google.com/webstore/detail/pretty-rest-api-documenta/fpbpajljjplbdpkijcnjocambjbigieb/related?hl=en&authuser=0
- Size: 7.44 MB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PrettyRestDoc
[Check it out the demo!](https://charlyjazz.github.io/prettyrestdoc/#User)
This is a template created in React to easily customize and build a REST API Documentation for commercial or development purposes. Project created using using create-react-app wth the typescript template
| Roles and Permissions | Preview Schema |
| :---------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: |
|  |  |
| Search | Endpoint Section |
| :---------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: |
|  |  |
### Merge Between custom content and your API contract
You can easily sync you OpenAPI 3 JSON File using the "SectionItem" structure. In the next example you can see a SectionItem create for the Store tag from the PetStore Swagger example. This way can add images, descriptions, and introductory sections like "Getting Started"
```javascript
const documentation: SectionItem = {
id: "store",
tag: "store",
schema: "Order",
title: "Store",
content: {
left_section_title: "Stores",
left_section_paragraphs: ["This is a Store related operation"],
right_box_snippet_white: true,
right_box_snippet_title: "Example of a Order object",
},
is_core_resource: true,
};
```
Structure of a `SectionItem`:
`id`: Anchor for URL
`tag`: Tag to found content inside the OpenAPI3 JSON file
`title`: Title for UI
`content`: Titles and descriptions. Also you can create a object like a example of a response/request.
`is_core_resource`: This boolean parameter help to split the content between sections like a "Getting Started" and the API endpoints
With a Array of SectionItems and the JSON of the OpenAPI Schema you can render the documentation:
```javascript
import docSwagger from "./petstore.json"; // OpenAPI JSON
import APIDoc from "./doc"; // Array of SectionItem
;
```
### Section for Roles and Permissions
You can create easily a table for roles and permissions sending the prop roles to the component. **The `SectionItem` need the `roles-permissions` id for this special case.**
```xml
```
Then you will need set the roles to each endpoint in the OpenAPI3 JSON.
```json
{
"put": {
"tags": ["user"],
"roles": ["admin"],
"summary": "Update user",
"description": "This can only be done by the logged in user.",
"operationId": "updateUser"
}
}
```
### Customization and Styles
The structure of the project is very easy to understand. The code of the documentation is inside the `src/lib` folder:
- `src/lib/adapter-ao3`: Logic to get content from OpenAPI3
- `src/lib/components`: All UI components, you can change styles or logic easily (Modules CSS implemented)
- `src/lib/hooks`: Hooks!
- `src/lib/PrettyRestDoc.jsx`: Root Component
### Current example in this Repository
This Repository have a example using the PetStore from Swagger with the sections Pet, Store and User. But with three sections introductories using the power of `SectionsItem` structures. Also there are a section for **Roles and Permissions**
### Run Documentation in your local Browser
```bash
npm install && npm run start
```
### Run Tests
```bash
npm install && npm run test
```
### Chrome Extension
### Credits
- [Swagger](https://swagger.io/)
- [OpenAPI](https://www.openapis.org/)