https://github.com/data-fair/openapi-viewer
Browse and test a REST API described with the OpenAPI 3.0 Specification
https://github.com/data-fair/openapi-viewer
api api-documentation openapi openapi3 swagger swagger-ui
Last synced: 3 months ago
JSON representation
Browse and test a REST API described with the OpenAPI 3.0 Specification
- Host: GitHub
- URL: https://github.com/data-fair/openapi-viewer
- Owner: data-fair
- License: agpl-3.0
- Created: 2017-03-14T18:12:56.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-12-06T13:44:39.000Z (almost 2 years ago)
- Last Synced: 2024-06-16T05:28:51.313Z (over 1 year ago)
- Topics: api, api-documentation, openapi, openapi3, swagger, swagger-ui
- Language: JavaScript
- Size: 2.6 MB
- Stars: 91
- Watchers: 8
- Forks: 9
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI viewer
This service is designed to easily browse and test a REST API described with the [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification).
## Sponsors
| | Click [here to support the development of this project](https://github.com/sponsors/koumoul-dev). |
|-|-|
|  | [Koumoul](https://koumoul.com) develops the Data Fair ecosystem and hosts it as an online service. |
|  | [Dawizz](https://dawizz.fr) uses the Data Fair ecosystem inside its platform and supports its development. |
## Parameters
### Query Parameters
- **drawerLocation** : The location of the navigation-drawer. Can be `left` or `right`. Defaults to `left`.
- **urlType** : The type of the URL defined in the environment variable `ALLOWED_URLS`.
- **operation** : The `operationId` of the operation to navigate to. [Reference : OpenAPI 3.1 Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object)
> ⚠️ **Deprecated**:
>
> - ~~**url** : The location of the API documentation file to load, in OpenAPI v3 JSON format.~~ *Replaced by the `urlType` query parameter instead and the `ALLOWED_URLS` environment variable.*
> - ~~**hide-toolbar** : `true` or `false` to hide the toolbar (useful for iframe integration). Defaults to `false`.~~
### Environment Variables
- **USE_SIMPLE_DIRECTORY** : A boolean to enable integration with **[SimpleDirectory](https://github.com/data-fair/simple-directory)**. Defaults to `false`.
- **DEFAULT_URL** : The default URL to load when no `urlType` query parameter is provided.
- **ALLOWED_URLS** : A JSON object containing a list of allowed URLs. The keys are used as the `urlType` query parameter. The values are the URLs to the OpenAPI files. These URLs can contain placeholders enclosed in curly braces {}, which will be replaced by the corresponding query parameters. The placeholders are defined by the keys of the query parameters. Defaults to an empty object.
> *Examples of ALLOWED_URLS :*
>
> ```json
> {
> "exampleYaml": "https://example1.com/openapi.yaml",
> "exampleWithUrlTemplate": "https://example2.com/{id}/openapi.json"
> }
> ```
## Integration with SimpleDirectory
By default, the viewer runs in **standalone mode** and does not integrate with **[SimpleDirectory](https://github.com/data-fair/simple-directory)**.
However, you can enable integration to benefit from:
- **Theming**: Automatically adapts to the platform's look and feel.
- **Language**: Uses the same language settings as the environment.
To enable integration with SimpleDirectory, set the environment variable:
```bash
USE_SIMPLE_DIRECTORY=true
```
## Developers
Take a look at the [contribution guidelines](./CONTRIBUTING.md).