npmpackage.info

@suin/esa-openapi

esa.io APIをOpenAPIで記述したJSONファイルを提供します。開発者はこれとOpenAPI Generatorのクライアント生成と組み合わせることで、C#, C++, Go, Rust, Java, Kotlin, Scala, PHP, Ruby, Python, Objective-C, Swift, Typescript, JavaScript, Dart, Elm, Haskellなど様々な言語でesa APIを呼び出せるようになります。

2.2.0

MIT

TypeScript

107.14 kB

2,191 2.5

Installations

npm install @suin/esa-openapi

Developer Guide

BETA

Typescript

No

Module System

CommonJS

Min. Node Version

>=14

Node Version

14.19.0

NPM Version

6.14.16 Pull Requests

Open

0

Total

1

Closed

0

Merged

1

Issues

Open

0

Total

0

Closed

0

Releases

v2.2.0

Published on 17 Mar 2022

v2.1.0

Published on 23 Apr 2021

v2.0.0

Published on 23 Apr 2021

v1.1.1

Published on 22 Apr 2021

v1.1.0

Published on 22 Apr 2021

v1.0.0

Published on 21 Apr 2021

View all 6 releases

Contributors

Unable to fetch Contributors

View all 3 contributors

Languages

TypeScript

HTML

Shell

TypeScript (99.09%)

HTML (0.82%)

Shell (0.1%)

Developer

suin

Download Statistics

Total Downloads

2,191

Last Day

Last Week

Last Month

Last Year

185

GitHub Statistics

6 Stars

27 Commits

1 Forks

2 Watching

1 Branches

3 Contributors

Maintainers

Package Meta Information

Latest Version

2.2.0

Package Id

@suin/esa-openapi@2.2.0

Unpacked Size

107.14 kB

Size

15.26 kB

File Count

NPM Version

6.14.16

Node Version

14.19.0

Total Downloads

Cumulative downloads

Total Downloads

2,191

Last day

Compared to previous day

Last week

Compared to previous week

Last month

337.5%

Compared to previous month

Last year

-70.8%

185

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Versions

@suin/esa-openapi

esa.io API v1 を OpenAPI 規格に基づいて定義したものです。

OpenAPI 定義ファイルはesa-api.jsonになります。

使い方

Swagger Editor で見る

Swagger Editor は、ブラウザ上で OpenAPI を編集したり、API ドキュメントをプレビューが見れるエディタです。

Swagger Editor で esa API を読み込むには次の手順を行ってください:

Swagger Editor を開く
メニューの「File」→「Import URL」でダイアログを開き、次の URL を入力する:
```
https://raw.githubusercontent.com/suin/esa-openapi/main/esa-api.json
```

エディタのプレビュー画面上では、認証情報を入力することで、実際の API にリクエストを送信することもできます。認証情報はプレビュー画面右上の「Authorize」を開き、「AccessTokenHeader」に本物の esa API アクセストークンを入力してください。(OAuth2 による認証方法はうまく動きません。)

ReDoc で見る

ReDoc は OpenAPI のファイルを読み込むだけで API ドキュメントを表示できる React ベースのウェブアプリケーションです。

» esa API を ReDoc で見る «

OpenAPI Generator でクライアントを生成する

OpenAPI Generator は様々な言語の API クライアントを生成できるツールです。

OpenAPI Generator のインストール

OpenAPI Generator は次の複数の方法でインストールできます。

NPM
Homebrew
Docker
JAR

詳細は公式ドキュメントをご覧ください。

ここでは NPM でインストールした OpenAPI Generator を用いてクライアントを生成する方法を説明します。

TypeScript のクライアントを生成する

TypeScript のクライアントを生成するには次のコマンドを実行します:

1npx @openapitools/openapi-generator-cli generate \
2    -g typescript-axios \
3    -i https://raw.githubusercontent.com/suin/esa-openapi/main/esa-api.json \
4    -o client \
5    --additional-properties=supportsES6=true,typescriptThreePlus=true,useSingleRequestParameter=true,withSeparateModelsAndApi=true,apiPackage=api,modelPackage=models

クライアントはclientディレクトリに生成されます。これを TypeScript で使うには次のようにします:

1import { Configuration, EsaApi } from "./client";
2
3(async () => {
4  const esaApi = new EsaApi(
5    new Configuration({ accessToken: process.env.ESA_API_TOKEN })
6  );
7  const { data } = await esaApi.getPosts({ teamName: "doc" });
8
9  for (const post of data.posts) {
10    console.log(post.name);
11  }
12})();

TypeScript は typescript-axios の他にも次のクライアントが生成できます:

typescript (experimental)
typescript-angular
typescript-angularjs-deprecated (deprecated)
typescript-aurelia
typescript-fetch
typescript-inversify
typescript-jquery
typescript-nestjs (experimental)
typescript-node
typescript-redux-query
typescript-rxjs

PHP のクライアントを生成する

Guzzle を用いた PHP クライアントライブラリが生成できます。

PHP のクライアントを生成するには次のコマンドを実行します:

1npx @openapitools/openapi-generator-cli generate \
2    -g php \
3    -i https://raw.githubusercontent.com/suin/esa-openapi/main/esa-api.json \
4    -o client \
5    --additional-properties=invokerPackage='YourOrg\YourProject'

NPM でインストールして使う

esa-api.json は NPM パッケージとして配布しています。npm でインストールすると JavaScript 上で読み込めます。

インストール方法:

1npm install @suin/esa-openapi

Node.js で読み込む方法:

1const esaOpenApi = require("@suin/esa-openapi");
2
3console.log(esaOpenApi);
4//=> {
5//   openapi: '3.0.0',
6//   info: {
7//     title: 'esa API v1',
8//     description: 'チームのナレッジ共有サービス[esa.io](https://esa.io/)のAPI v1の仕様書',
9//     version: '1.0.0',
10//     termsOfService: 'https://docs.esa.io/posts/5',
11//     'x-logo': {
12//       url: 'https://img.esa.io/uploads/production/attachments/3/2018/11/13/2/fe8f24a1-a23d-4c96-951c-f6f4433d1399.png',
13//       altText: 'esa'
14//     }
15//   },
16// ...

開発に参加する

このプロジェクトの開発に参加する方法について説明します。

変更等はプルリクエストを下さい。
esa-api.json は直接編集しないようにお願いします。

パッケージマネージャー

パッケージマネージャーは PNPM をお使い下さい。

このプロジェクトをクローンしたら次のコマンドでパッケージをインストールします:

1pnpm install

本プロジェクトのアプローチ

esa API はそれなりの規模になるため、OpenAPI のファイルひとつとして管理するのが難しいです。そこで、このプロジェクトでは esa API を TypeScript で記述し、プログラムによって esa-api.json を生成するアプローチをとっています。

TypeScript ファイルの構成

esa API の記述は複数の TypeScript ファイルに分割しています。これらファイルの構造は主に次の通りになっています。

headers/: リクエストレスポンスヘッダに関する記述
parameters/: リクエストのパスやクエリーのパラメーター関する記述
paths/: パスに関する記述。このディレクトリ構成は URL と一致するようになっています。
schemas/: リクエストやレスポンスに含まれる JSON などのオブジェクトの記述
spec.ts: API 仕様の全体像を記述

esa-api.json の変更方法

esa-api.json を生成するには次のコマンドを実行してください:

1pnpm generate:spec

esa-api.json のバリデーション

esa-api.json をバリデーションするには次のコマンドを実行してください:

1pnpm validate:spec

※実行には Java8 が必要です。

esa-api.json に基づいて TypeScript クライアントを生成する

クライアントライブラリを生成するには次のコマンドを実行してください:

1pnpm generate:client

※実行には Java8 が必要です。

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

0

Security-Policy

Determines if the project has published a security policy.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

40 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-4jpv-8r57-pv7j
Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
Warn: Project is vulnerable to: GHSA-cph5-m8f7-6c5x
Warn: Project is vulnerable to: GHSA-wf5p-g6vw-rhxx
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-w8qv-6jwh-64r5
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
Warn: Project is vulnerable to: GHSA-74fj-2j2h-c42q
Warn: Project is vulnerable to: GHSA-pw2r-vq6v-hr8c
Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-5v2h-r2cx-5xgj
Warn: Project is vulnerable to: GHSA-rrrm-qjm4-v8hf
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
Warn: Project is vulnerable to: GHSA-px4h-xg32-q955
Warn: Project is vulnerable to: GHSA-hj9c-8jmm-8c52
Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Warn: Project is vulnerable to: GHSA-x2pg-mjhr-2m5x
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-44c6-4v22-4mhx
Warn: Project is vulnerable to: GHSA-4x5v-gmq8-25ch
Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
Warn: Project is vulnerable to: GHSA-jgrx-mgxx-jf9v
Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v
Warn: Project is vulnerable to: GHSA-38fc-wpqx-33j7
Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Warn: Project is vulnerable to: GHSA-6fc8-4gx4-v693
Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q

Score

2.5

/10

Last Scanned on 2025-01-27

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

@suin/esa-openapi

Installations

Developer Guide

No

CommonJS

>=14

14.19.0

6.14.16

Pull Requests

0

1

0

1

Issues

0

0

0

Releases

Contributors

Unable to fetch Contributors

Languages

Developer

suin

Download Statistics

GitHub Statistics

Maintainers

Package Meta Information

Total Downloads

2,191

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

@suin/esa-openapi

使い方

Swagger Editor で見る

ReDoc で見る

OpenAPI Generator でクライアントを生成する

OpenAPI Generator のインストール

TypeScript のクライアントを生成する

PHP のクライアントを生成する

NPM でインストールして使う

開発に参加する

パッケージマネージャー

本プロジェクトのアプローチ

TypeScript ファイルの構成

esa-api.json の変更方法

esa-api.json のバリデーション

esa-api.json に基づいて TypeScript クライアントを生成する

10

10

10

0

0

0

0

0

0

0

0

0

0

2.5

/10