OpenDocumenter - GitLite

KO | EN

gitlite — search

#javascript #react #llm #go #android #deep-learning #linux #macos #java #kubernetes #vue #pytorch #openai #open-source

OpenDocumenter

(★ 169)

OpenDocumenter is a automatic documentation generator for OpenAPI v3 schemas. Simply provide your schema file in JSON or YAML, then sit back and enjoy the documentation.

파일 탐색기

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

- - bug_report.md
  - feature_request.md
- - codeql-analysis.yml
  - greetings.yml
  - label.yml
  - quisque.yml
- dependabot.yml
- labeler.yml
- PULL_REQUEST_TEMPLATE.md
- config.json
- example.gif
- ghes-2.20.yml
- openapi.yml
- - highlighter-theme-dark.less
  - highlighter-theme-light.less
  - theme.less
  - utils.less
- - ContactTeam.vue
  - DocEntry.vue
  - DocEntryTitle.vue
  - DocFooter.vue
  - DocHeader.vue
  - DocLayout.vue
  - DocSidebar.vue
  - DocSidebarEntry.vue
  - DocSidebarTag.vue
  - DocTag.vue
  - DocToolbox.vue
  - DocToolboxDropdown.vue
  - DocToolboxIcon.vue
  - Endpoint.vue
  - Example.vue
  - Highlight.vue
  - Markdown.vue
  - ReqBody.vue
  - ReqResponse.vue
  - Shield.vue
  - SplitSection.vue
  - StatusCode.vue
- - codegen.js
  - envInject.js
- .babelrc
- .browserslistrc
- environment.json
- index.html
- index.js
- index.vue
- store.js
- vue.config.js
- cli.js
- index.js
.gitignore
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE.md
package.json
README.md
SECURITY.md
yarn.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/ouropencode/OpenDocumenter

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

cd OpenDocumenter

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

2. Node.js

쉬움 추천

사전 준비물

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

> npm install -g opendocumenter

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

> yarn global add opendocumenter

이 명령어를 터미널에 그대로 입력해 실행하세요.

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

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">OpenDocumenter</h1>

<p align="center">
  <img alt="Version" src="https://img.shields.io/github/package-json/v/ouropencode/OpenDocumenter" />
  <img alt="npm" src="https://img.shields.io/npm/v/opendocumenter" />
  <img alt="License" src="https://img.shields.io/github/license/ouropencode/OpenDocumenter" />
  <img alt="Dependencies" src="https://img.shields.io/librariesio/release/npm/opendocumenter" />
  <img alt="Issues" src="https://img.shields.io/github/issues/ouropencode/OpenDocumenter" />
  <img alt="Node Version" src="https://img.shields.io/node/v/opendocumenter" />
  <img alt="Build Status" src="https://github.com/ouropencode/OpenDocumenter/workflows/Quisque%20API%20Build/badge.svg" />
</p>

<p align="center">
  <a href="https://ouropencode.github.io/OpenDocumenter/" target="_blank">
    <img alt="Node Version" src="https://raw.githubusercontent.com/ouropencode/OpenDocumenter/master/example/example.gif" />
  </a>
</p>

OpenDocumenter is a automatic documentation generator for [OpenAPI v3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) schemas. Simply provide your schema file in JSON or YAML, then sit back and enjoy the documentation.

Powered by [nuxt.js](https://nuxtjs.org/https://nuxtjs.org/) and [swagger-parser](https://github.com/swagger-api/swagger-parser).

## Example
For a live preview of documentation generated with OpenDocumenter you can view our demo documentation "**[Quisque API](https://ouropencode.github.io/OpenDocumenter/)**". This example uses lorem-ipsum for all content to provide placeholder text used to demonstrate the form of a document without relying on meaningful content.

## Installation

```bash
> npm install -g opendocumenter
```
or
```bash
> yarn global add opendocumenter
```

## Usage
```
> opendocumenter --help

_____             ____                            _
  |     |___ ___ ___|    \ ___ ___ _ _ _____ ___ ___| |_ ___ ___
  |  |  | . | -_|   |  |  | . |  _| | |     | -_|   |  _| -_|  _|
  |_____|  _|___|_|_|____/|___|___|___|_|_|_|___|_|_|_| |___|_|
        |_|

OpenDocumenter is a automatic documentation generator for OpenAPI v3 schemas.
  Simply provide your schema file in JSON or YAML, then sit back and enjoy the documentation.

Powered by nuxt.js and swagger-parser.

Usage:

opendocumenter --schema=<file> --output=<dir>

Arguments:

--schema=<file>    (required) The OpenAPI 3 format file to generate documentation from.
    --output=<dir>     (required) The output destination directory.
    --config=<file>    A configuration file to load advanced options from.
```

## Configuration
OpenDocumenter can be configured using a `.json` file stored alongside your schema file.

### Merge From Directory
The `mergeFromDirectory` parameter allows you to specify a directory that will be copied over the base template before building. This allows customization of any part of OpenDocumenter to suit your needs.

```json
{
  "mergeFromDirectory": "./overrides"
}
```

Any part of the OpenDocumenter vue source (see: [./src](./src)) can be overridden, just ensure to follow the same directory structure!
```
overrides
 |- assets
 | '- theme.less
 '- components
   |- DocHeader.vue
   '- DocEntry.vue
```

### 'Generated Using' Footer
By default, a small 'Generated Using' message is included on the footer of the generated documentation. Although we'd love you to keep it, you can disable this by setting the `disableGeneratedUsingFooter` parameter to true.

```json
{
  "disableGeneratedUsingFooter": true
}
```

### Aborting on Invalid Schema
OpenDocumenter is capable of generating documentation for OpenAPI schemas that don't match the OpenAPI Specification entirely. When generating we attempt to validate your schema, display any validation warnings, and then continue to generate. If you would like the generation to abort when a schema is invalid you can set the `abortOnInvalidSchema` parameter to true.

```json
{
  "abortOnInvalidSchema": true
}
```

### Shields / Badges
Various shields are included in the generated documentation header, such as the API version. Additional shields can be added using the `shields` parameter. Each shield is an object containing either the `url` key, or a combination of `left`, `right` and `color`. The `translate` parameter can be used (`left`, `right`, `both`) to run the text through the internationalization handler. An optional link can provided with the `href` parameter. All shields are generated using [shields.io](https://shields.io) unless a URL is provided.

```json
{
  "shields": [
    { "url": "https://img.shields.io/badge/test-1.2.3--test-blue" },
    { "left": "test", "right": "1.2.3-test", "color": "blue" },
    {
      "left": "test",
      "right": "1.2.3-test",
      "color": "blue",
      "href": "https://www.example.com"
    }
  ]
}
```

### Build: Modern Mode
By default, the build-chain produces "Modern Mode"  output, shipping native ES2015 code to modern browsers that support it, with auto fallback to a legacy bundle. This can be turned off by setting `vueModernMode` parameter, afterwards the build-chain produces "Legacy" output for older browser compatibility.

```json
{
  "vueModernMode": false
}
```

### Build: Reporting
You can control the reporting output from the build-chain with the `vueReport` parameter. This defaults to `none` and can be set to `json`, `html` or `both`. With this enabled the build-chain will output a report file describing the webpack bundle.

```json
{
  "vueReport": "html"
}
```

### Internationalization
Most of the documentation text is taken directly from the OpenAPI schema file, however, there are various strings throughout the project that cannot be stored within the schema file. All of these strings are customizable by editing the `i18n` parameter.
```json
{
  "i18n": {
    "API_SDK_DOCUMENTATION": "API and SDK Documentation",
    "VERSION": "version",
    "NO_INDEPTH_DOCS_AVAILABLE_ENDPOINT": "No in-depth API documentation is available for this endpoint.",
    "NO_INDEPTH_DOCS_AVAILABLE_TAG": "No in-depth API documentation is available for this section.",
    "CLICK_TO_COPY": "click to copy",
    "COPIED": "copied",
    "REQUEST_BODY": "Request Body",
    "REQUEST_RESPONSES": "Request Responses",
    "DEFINITION": "Definition",
    "DEFINITIONS": "Definitions",
    "SERVER": "Server",
    "LANGUAGE": "Language",
    "GENERATED_USING": "Generated using OpenDocumenter by $ourOpenCode",
    "HAVE_ANY_QUESTIONS_CONTACT": "Have any questions? Please contact",
    "US": "us",
    "OR": "or",
    "VIA_EMAIL": "via email",
    "VIA_OUR_WEBSITE": "via our website",
    "TERMS_OF_SERVICE": "Terms of Service",
    "SEND_US_AN_EMAIL": "Send us an email",
    "VISIT_OUR_WEBSITE": "Visit our website",
    "EXTERNAL_DOCUMENTATION": "External Documentation",
    "DOCUMENTATION": "Documentation"
  }
}
```

> There is a single end-user visible string that isn't configurable in this config. The "Loading Documentation..." text in the page title, briefly shown during page load, is only configurable using the "Merge From Directory" parameter.

## License
Licensed under the MIT license. Please see [LICENSE](LICENSE) for more details.