Skip to content

Docs: Consolidate About pages, Highlight Maintainers, Consolidate Contributors #2122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 14, 2025
Merged

Docs: Consolidate About pages, Highlight Maintainers, Consolidate Contributors #2122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 3 additions & 14 deletions docs/.vitepress/en.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ export default defineConfig({
{ text: "Testing", link: "/openapi-fetch/testing" },
{ text: "Examples", link: "/openapi-fetch/examples" },
{ text: "API", link: "/openapi-fetch/api" },
{ text: "About", link: "/openapi-fetch/about" },
],
},
],
Expand All @@ -52,7 +51,6 @@ export default defineConfig({
{ text: "Examples", link: "/examples" },
{ text: "Migrating from 6.x", link: "/migration-guide" },
{ text: "Advanced", link: "/advanced" },
{ text: "About", link: "/about" },
],
},
{
Expand All @@ -66,7 +64,6 @@ export default defineConfig({
{ text: "Testing", link: "/openapi-fetch/testing" },
{ text: "Examples", link: "/openapi-fetch/examples" },
{ text: "API", link: "/openapi-fetch/api" },
{ text: "About", link: "/openapi-fetch/about" },
],
},
{
Expand All @@ -76,15 +73,8 @@ export default defineConfig({
{ text: "Getting Started", link: "/" },
{ text: "useQuery", link: "/use-query" },
{ text: "useMutation", link: "/use-mutation" },
{
text: "useSuspenseQuery",
link: "/use-suspense-query",
},
{
text: "queryOptions",
link: "/query-options",
},
{ text: "About", link: "/about" },
{ text: "useSuspenseQuery", link: "/use-suspense-query" },
{ text: "queryOptions", link: "/query-options" },
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we forgot to add use useInfiniteQuery here @drwpow

Copy link
Contributor Author

@drwpow drwpow Jan 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh that’s a good callout thank you! I was running through the docs and noticed there are some formatting differences between all the packages—APIs are not only written differently but also split up across pages. I’ll make sure they’re in the sidebar in a PR that makes everything consistent.

My philosophy is first just write the docs, then worry about formatting and consistency later. Inconsistent docs are a great problem to have—it means a) they exist, and b) multiple people contributed to them, so the most important parts are done

],
},
{
Expand All @@ -97,7 +87,6 @@ export default defineConfig({
{ text: "useImmutable", link: "/use-immutable" },
{ text: "useInfinite", link: "/use-infinite" },
{ text: "useMutate", link: "/use-mutate" },
{ text: "About", link: "/about" },
],
},
{
Expand All @@ -118,9 +107,9 @@ export default defineConfig({
],
},
{ text: "Examples", link: "/openapi-metadata/examples" },
{ text: "About", link: "/openapi-metadata/about" },
],
},
{ text: "About", link: "/about" },
],
},
search: {
Expand Down
5 changes: 1 addition & 4 deletions docs/.vitepress/ja.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ export default defineConfig({
{ text: "使用例", link: "/ja/examples" },
{ text: "6.xからのマイグレーション", link: "/ja/migration-guide" },
{ text: "高度な機能", link: "/ja/advanced" },
{ text: "概要", link: "/ja/about" },
],
},
{
Expand All @@ -38,7 +37,6 @@ export default defineConfig({
{ text: "テスト", link: "/ja/openapi-fetch/testing" },
{ text: "使用例", link: "/ja/openapi-fetch/examples" },
{ text: "API", link: "/ja/openapi-fetch/api" },
{ text: "概要", link: "/ja/openapi-fetch/about" },
],
},
{
Expand All @@ -48,7 +46,6 @@ export default defineConfig({
{ text: "useQuery", link: "/ja/openapi-react-query/use-query" },
{ text: "useMutation", link: "/ja/openapi-react-query/use-mutation" },
{ text: "useSuspenseQuery", link: "/ja/openapi-react-query/use-suspense-query" },
{ text: "概要", link: "/ja/openapi-react-query/about" },
],
},
],
Expand Down Expand Up @@ -111,4 +108,4 @@ export const jaSearch: DefaultTheme.AlgoliaSearchOptions["locales"] = {
},
},
},
};
};
44 changes: 44 additions & 0 deletions docs/.vitepress/theme/Contributors.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<script setup lang="ts">
defineProps<{
contributors: {
username: string;
avatar: string;
links: { icon: string; link: string }[];
title?: string;
}[];
}>();
</script>

<style scoped>
.contributor-list {
gap: 0.75rem;
display: flex;
flex-wrap: wrap;
list-style: none;
margin: 0;
padding: 0;
}

.contributor-list li {
border-radius: 50%;
margin: 0;
overflow: hidden;
padding: 0;
}

.contributor-avatar {
display: block;
height: 3rem;
width: 3rem;
}
</style>

<template>
<ul class="contributor-list">
<li v-for="contributor in contributors" :key="contributor.username">
<a :href="contributor.links[0].link" :title="contributor.name">
<img class="contributor-avatar" width="48" height="48" :src="contributor.avatar" :alt="contributor.name" />
</a>
</li>
</ul>
</template>
2 changes: 0 additions & 2 deletions docs/.vitepress/zh.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ export default defineConfig({
{ text: "Node.js API", link: "/zh/node" },
{ text: "示例", link: "/zh/examples" },
{ text: "高级功能", link: "/zh/advanced" },
{ text: "关于", link: "/zh/about" },
],
},
{
Expand All @@ -37,7 +36,6 @@ export default defineConfig({
{ text: "测试", link: "/zh/openapi-fetch/testing" },
{ text: "示例", link: "/zh/openapi-fetch/examples" },
{ text: "API", link: "/zh/openapi-fetch/api" },
{ text: "关于", link: "/zh/openapi-fetch/about" },
],
},
],
Expand Down
14 changes: 10 additions & 4 deletions docs/6.x/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ description: Additional info about this project

<script setup>
import { VPTeamMembers } from 'vitepress/theme';
import contributors from '../data/contributors.json';
import Contributors from '../.vitepress/theme/Contributors.vue'
import data from '../data/contributors.json';
</script>

# About openapi-typescript
Expand All @@ -27,7 +28,6 @@ description: Additional info about this project
- [**Revolt**](https://github.com/revoltchat/api): open source user-first chat platform
- [**Spacebar**](https://github.com/spacebarchat): a free, open source, self-hostable Discord-compatible chat/voice/video platform
- [**Supabase**](https://github.com/supabase/supabase): The open source Firebase alternative.
- [**Twitter API**](https://github.com/twitterdev/twitter-api-typescript-sdk): Official SDK for the Twitter API

## Project goals

Expand All @@ -54,8 +54,14 @@ These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternat

If you fit into this usecase, it’s a great experience! But for everyone else, openapi-typescript (and openapi-fetch) is a more flexible, lower-level solution that can work for any technology choice (or even be incrementally-adopted without any cost).

## Maintainers

This library is currently maintained by these amazing individuals:

<VPTeamMembers size="small" :members="data.maintainers" />

## Contributors

This library wouldn’t be possible without all these amazing contributors:
And thanks to 100+ amazing contributors, without whom these projects wouldn’t be possible:

<VPTeamMembers size="small" :members="contributors['openapi-typescript']" />
<Contributors :contributors="data.contributors" />
40 changes: 28 additions & 12 deletions docs/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ description: Additional info about this project

<script setup>
import { VPTeamMembers } from 'vitepress/theme';
import contributors from './data/contributors.json';
import Contributors from './.vitepress/theme/Contributors.vue'
import data from './data/contributors.json';
</script>

# About openapi-typescript
Expand All @@ -27,34 +28,49 @@ description: Additional info about this project
- [**Revolt**](https://github.com/revoltchat/api): open source user-first chat platform
- [**Spacebar**](https://github.com/spacebarchat): a free, open source, self-hostable Discord-compatible chat/voice/video platform
- [**Supabase**](https://github.com/supabase/supabase): The open source Firebase alternative.
- [**Twitter API**](https://github.com/twitterdev/twitter-api-typescript-sdk): Official SDK for the Twitter API
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Who cares anymore


## Project goals

### openapi-typescript

1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like [enums](https://www.typescriptlang.org/docs/handbook/enums.html).
1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
1. Support fetching OpenAPI schemas from files as well as local and remote servers.

## Differences
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: the differences are removed; I debate whether or not these are useful. If we think they are, they should probably go in the intro?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for folks evaluating openapi-typescript, this can be very useful (and IMO having reasonable differences listed is usually a sign for the health of the project).

Appending them to the end of "Introduction" or even leaving them here in an appropriate subsection seem fine to me.

Looking at the other edits, it does make me wonder if we should rename "About" to "Project Goals". It feels to me that both the goals and the differences have a better home under the individual headers.

(We might want to consider a overall about page with a higher level goal, like "We take OpenAPIs and make useful typescript stuff with it", of course, we need to first agree on that one :P).

In the interest of time, I have not reviewed below this comment yet. Let's settle on overall structure first.

### openapi-fetch

1. Types should be strict and inferred automatically from OpenAPI schemas with the absolute minimum number of generics needed.
2. Respect the native Fetch API while reducing boilerplate (such as `await res.json()`).
3. Be as light and performant as possible.

### openapi-react-query

1. Types should be strict and inferred automatically from OpenAPI schemas with the absolute minimum number of generics needed.
2. Respect the original `@tanstack/react-query` APIs while reducing boilerplate.
3. Be as light and performant as possible.

### vs. swagger-codegen
### swr-openapi

openapi-typescript was created specifically to be a lighter-weight, easier-to-use alternative to swagger-codegen that doesn’t require the Java runtime or running an OpenAPI server. Nor does it generate heavyweight client-side code. In fact, all the code openapi-typescript generates is **runtime free static types** for maximum performance and minimum client weight.
1. Types should be strict and inferred automatically from OpenAPI schemas with the absolute minimum number of generics needed.
2. Respect the original `swr` APIs while reducing boilerplate.
3. Be as light and performant as possible.

### vs. openapi-typescript-codegen
### openapi-metadata

These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternative to the original swagger-codegen, but ends up being the same in practice. openapi-typescript has the same advantage of being **runtime free** whereas openapi-typescript-codegen can generate some pretty heavy bundles, up to `250 kB` or more depending on the schema complexity.
1. Must respect the OpenAPI V3 specification
2. Be extensible and easily integrated inside backend frameworks
3. Be focused around developer experience

### vs. tRPC
## Maintainers

[tRPC](https://trpc.io/) is an opinionated type-safe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).
This library is currently maintained by these amazing individuals:

If you fit into this use case, it’s a great experience! But for everyone else, openapi-typescript (and openapi-fetch) is a more flexible, lower-level solution that can work for any technology choice (or even be incrementally-adopted without any cost).
<VPTeamMembers size="small" :members="data.maintainers" />

## Contributors

This library wouldn’t be possible without all these amazing contributors:
And thanks to 100+ amazing contributors, without whom these projects wouldn’t be possible:

<VPTeamMembers size="small" :members="contributors['openapi-typescript']" />
<Contributors :contributors="data.contributors" />
2 changes: 1 addition & 1 deletion docs/data/contributors.json
View file
Open in desktop

Large diffs are not rendered by default.

30 changes: 17 additions & 13 deletions docs/ja/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ description: このプロジェクトに関する追加情報

<script setup>
import { VPTeamMembers } from 'vitepress/theme';
import contributors from '../data/contributors.json';
import Contributors from '../.vitepress/theme/Contributors.vue'
import data from '../data/contributors.json';
</script>

# openapi-typescriptについて
Expand All @@ -27,34 +28,37 @@ description: このプロジェクトに関する追加情報
- [**Revolt**](https://github.com/revoltchat/api): オープンソースのユーザー優先チャットプラットフォーム
- [**Spacebar**](https://github.com/spacebarchat): 無料でオープンソースの自ホスト可能な Discord 互換のチャット/音声/ビデオプラットフォーム
- [**Supabase**](https://github.com/supabase/supabase): オープンソースの Firebase 代替
- [**Twitter API**](https://github.com/twitterdev/twitter-api-typescript-sdk): Twitter API の公式 SDK

## プロジェクトの目標

### openapi-typescript

1. 任意の有効な OpenAPI スキーマを TypeScript 型に変換できるようにすること。どんなに複雑なスキーマでも対応可能です。
2. 生成される型は静的に解析可能で、実行時の依存関係がない（ただし、[enums](https://www.typescriptlang.org/docs/handbook/enums.html) のような例外はあります）。
3. 生成された型は、元のスキーマにできるだけ一致し、元の大文字形式などを保持します。
4. 型の生成 は Node.js だけで実行可能であり、（Java、Python などは不要）どんな環境でも実行できます。
5. ファイルからの OpenAPI スキーマのフェッチや、ローカルおよびリモートサーバーからのフェッチをサポートします。

## 比較

### vs. swagger-codegen
### openapi-fetch

openapi-typescript は、swagger-codegen の軽量で使いやすい代替手段として作成されており、Java ランタイムや OpenAPI サーバーを実行する必要はありません。また、大規模なクライアントサイドコードも生成しません。実際、openapi-typescript が生成するすべてのコードは、**実行時の依存関係がない静的型** であり、最大のパフォーマンスと最小のクライアント負荷を実現します。
1. 型は厳密で、最小限のジェネリクスで OpenAPI スキーマから自動的に推論されるべきです。
2. ネイティブの Fetch API を尊重しつつ、（`await res.json()` などの）ボイラープレートを削減すること。
3. 可能な限り軽量で高性能であること。

### vs. openapi-typescript-codegen
### openapi-react-query

openapi-typescript-codegen は、元の swagger-codegen の Node.js 代替手段ですが、実際には同じものです。openapi-typescript は、openapi-typescript-codegen と同様に、**実行時の依存関係がない** という利点を持っていますが、openapi-typescript-codegen は、スキーマの複雑さに応じて `250 kB` 以上になるかなり大きなバンドルを生成する可能性があります。
1. 型は厳格であり、必要最小限のジェネリクスでOpenAPIスキーマから自動的に推論されるべきです。
2. 元の `@tanstack/react-query` API を尊重しつつ、ボイラープレートを減らします。
3. できるだけ軽量でパフォーマンスが高くなるようにします。

### vs. tRPC
## メインテナー
Copy link
Contributor Author

@drwpow drwpow Jan 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my barely-JLPT5 proficiency led me to make this guess for a new heading. I don’t feel confident trying to write entire sentences though (I would never run something through Google Translate)


[tRPC](https://trpc.io/) は、強い設計方針を持ったサーバーとクライアントの両方で型の安全性を提供するフレームワークです。これは、サーバーとクライアントの両方が tRPC で記述されていることを要求します（つまり、バックエンドが Node.js を使用しています）。
This library is currently maintained by these amazing individuals:

このユースケースに合っているならば、素晴らしい体験ができるでしょう！しかし、他のすべての場合において、openapi-typescript（および openapi-fetch）は、あらゆる技術選択に適応できる、より柔軟で低レベルなソリューションです（コストなしで段階的に導入することさえできます）。
<VPTeamMembers size="small" :members="data.maintainers" />

## 貢献者

これらの素晴らしい貢献者がいなければ、このライブラリは存在しなかったでしょう：
And thanks to 100+ amazing contributors, without whom these projects wouldn’t be possible:

<VPTeamMembers size="small" :members="contributors['openapi-typescript']" />
<Contributors :contributors="data.contributors" />
48 changes: 0 additions & 48 deletions docs/ja/openapi-fetch/about.md
View file
Open in desktop

This file was deleted.

23 changes: 0 additions & 23 deletions docs/ja/openapi-react-query/about.md
View file
Open in desktop

This file was deleted.

Loading
Loading