nestjs-redoc - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #ai #golang #machine-learning #rust #linux #docker #nodejs #java #cli #kubernetes #awesome-list #open-source

nestjs-redoc

(★ 155)

📘 ReDoc frontend for you NestJS swagger API documentation

파일 탐색기

최종 버전 다운로드 (.zip)

- .gitkeep
- - cats.controller.ts
  - cats.module.ts
  - cats.service.ts
- app.module.ts
- main.ts
- - index.ts
  - redocDocument.interface.ts
  - redocOptions.interface.ts
- - index.spec.ts
  - index.ts
  - options.model.spec.ts
  - options.model.ts
- index.spec.ts
- index.ts
- redoc-module.spec.ts
- redoc-module.ts
- redoc.handlebars
.editorconfig
.eslintrc.js
.gitignore
.huskyrc
.npmignore
.prettierignore
.prettierrc
commitlint.config.js
jest.config.js
LICENSE
package.json
README.md
redoc.png
tsconfig.build.json
tsconfig.json
yarn.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/ojoanalogo/nestjs-redoc

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd nestjs-redoc

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm start

개발/실행 서버를 켭니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">
  NestJS-Redoc
  <h4 align="center">ReDoc powered frontend for your NestJS API spec</h4>
</h1>

<div align="center">
  <a href="http://makeapullrequest.com">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs welcome" />
  </a>
  <a href="https://github.com/nestjs/nest">
    <img src="https://raw.githubusercontent.com/nestjsx/crud/master/img/nest-powered.svg?sanitize=true" alt="Nest Powered" />
  </a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</div>

<div align="center">

[⚡ Features](#-Features) |
[🗿 Installation](#-Installation) |
[❓ How to use](#-How-to-use) |
[👨‍💻👩‍💻 Contributors](#--Contributors) |
[📜 Changelog](#-Changelog) |
[📋 ToDo](#-ToDo)

</div>

<img src="./redoc.png"/>

<p align="center">

📒 This is a [ReDoc](https://github.com/Redocly/redoc) powered frontend for your NestJS API spec.

</p>

## ⚡ Features

- Customizable theme
- It's almost a drop in replacement for you current swagger UI, you only need to import this package and modify any settings you may want to change (e.g: Page title, ReDoc options)

## 🗿 Installation

Using npm: `npm i nestjs-redoc`

Using yarn: `yarn add nestjs-redoc`

## ❓ How to use

You need to install the [Swagger Module](https://github.com/nestjs/swagger) first if you want to get definitions updated with your project.

In future versions you will be able to pass a URL parameter as document, but for the moment you need this document object from the swagger module

```typescript
const options = new DocumentBuilder()
  .setTitle('Look, i have a title')
  .setDescription('A very nice description')
  .setBasePath('/api/v1')
  .build();
const document = SwaggerModule.createDocument(app, options);
```

Then add the following example code.

**Note**: All properties are optional, if you don't specify a title we will fallback to the one you used in your DocumentBuilder instance.

```typescript
const redocOptions: RedocOptions = {
  title: 'Hello Nest',
  logo: {
    url: 'https://redocly.github.io/redoc/petstore-logo.png',
    backgroundColor: '#F0F0F0',
    altText: 'PetStore logo'
  },
  sortPropsAlphabetically: true,
  hideDownloadButton: false,
  hideHostname: false,
  auth: {
    enabled: true,
    user: 'admin',
    password: '123'
  },
  tagGroups: [
    {
      name: 'Core resources',
      tags: ['cats'],
    },
  ],
};
// Instead of using SwaggerModule.setup() you call this module
await RedocModule.setup('/docs', app, document, redocOptions);
```

## Available options

### Redoc Options

| Option                  | Description                                                                                                                                           | Type              | Note                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------ |
| title                   | Web site title (e.g: ReDoc documentation)                                                                                                             | string            |
| favicon                 | Web site favicon URL                                                                                                                                  | string            | Fallbacks to the document title if not set |
| logo                    | Logo options                                                                                                                                          | LogoOptions       | See LogoOptions table                      |
| theme                   | Theme options                                                                                                                                         | ThemeOptions      | See ThemeOptions info                      |
| untrustedSpec           | If set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS, by default is false                                       | boolean           |
| supressWarnings         | If set, warnings are not rendered at the top of documentation (they are still logged to the console)                                                  | boolean           |
| hideHostname            | If set, the protocol and hostname won't be shown in the operation definition                                                                          | boolean           |
| expandResponses         | Specify which responses to expand by default by response codes, values should be passed as comma-separated list without spaces (e.g: 200, 201, "all") | string            |
| requiredPropsFirst      | If set, show required properties first ordered in the same order as in required array                                                                 | boolean           |
| sortPropsAlphabetically | If set, propeties will be sorted alphabetically                                                                                                       | boolean           |
| showExtensions          | If set the fields starting with "x-" will be shown, can be a boolean or a string with names of extensions to display                                  | boolean           |
| noAutoAuth              | If set, redoc won't inject authentication section automatically                                                                                       | boolean           |
| pathInMiddlePanel       | If set, path link and HTTP verb will be shown in the middle panel instead of the right one                                                            | boolean           |
| hideLoading             | If set, loading spinner animation won't be shown                                                                                                      | boolean           |
| nativeScrollbars        | If set, a native scrollbar will be used instead of perfect-scroll, this can improve performance of the frontend for big specs                         | boolean           |
| hideDownloadButton      | This will hide the "Download spec" button, it only hides the button                                                                                   | boolean           |
| disableSearch           | If set, the search bar will be disabled                                                                                                               | boolean           |
| onlyRequiredInSamples   | Shows only required fileds in request samples                                                                                                         | boolean           |
| auth                    | Auth options                                                                                                                                          | AuthOptions       | See AuthOptions info                       |
| AuthOptions info        |
| enabled                 | If enabled, a prompt will pop out asking for authentication details, default: `false`                                                                 | boolean           |
| user                    | User name, default: `admin`                                                                                                                           | string            |
| password                | User password, default: `123`                                                                                                                         | string            |
| tagGroups               | Tag groups options                                                                                                                                    | TagGroupOptions[] | See Tag Group options                      |
| Tag Group options info  |
| name                    | Tag name                                                                                                                                              | string            |
| tags                    | Tag collection                                                                                                                                        | string[]          |
| redocVersion            | Set an specific redoc version                                                                                                                         | string,number     | By default it's "latest"                   |

**Note**: If you want to change your ReDoc theme settings, take a look at the official ReDoc documentation: <https://github.com/Redocly/redoc/blob/master/src/theme.ts>

Apply the properties defined in ResolvedThemeInterface to the key called "theme" in the redoc options

### Logo options

| Option          | Description                                                                           | Type   | Example  |
| --------------- | ------------------------------------------------------------------------------------- | ------ | -------- |
| url             | The URL pointing to the spec Logo, must be in the format of a URL and an absolute URL | string |
| backgroundColor | Background color to be used, must be RGB color in hexadecimal format (e.g: #008080)   | string | #F0F0F0  |
| altText         | Alt tag for Logo                                                                      | string | PetStore |
| href            | href tag for Logo, it defaults to the host used for your API spec                     | string |

## 👨‍💻👩‍💻 Contributors

- Special thanks to [Jay McDoniel (jmcdo29)](https://github.com/jmcdo29) who helped with code refactoring and unit tests! 👏
- @joemaidman

## 📜 Changelog

Bellow are a list of changes, some might go undocumented

- 1.0.0 - First release
- 1.1.0 - Minor changes, nothing too important
- 1.2.0 - Added unit tests, refactored code
- 1.2.1 - Updated to work with the latest version of nest swagger module
- 1.2.2 - Fixed issue with URL on windows
- 1.3.0 - Added favicon option (by @joemaidman)
- 2.0.0 - Added authentication option, fixed issues with CSP and nestjs version compatibility issues
- 2.1.0 - Added x-tagGroups extension property
- 2.1.1 - Fixed CSP issue on Safari browser
- 2.2.0 - Added version property, this way you can pin redoc to a specific version
- 2.2.2 - Updated to support Nest 8

## 📋 ToDo

- Add Fastify support
- Add the option to use a spec URL instead of document
- Fix tests