Update doc #98
Update doc #98
Conversation
WalkthroughThis pull request introduces a variety of documentation files and updates within the Changes
Possibly related PRs
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Outside diff range and nitpick comments (5)
docs/docs/02_getting-started.md (1)
52-52: Consider adding missing articles.To improve the readability of the documentation, consider adding the missing articles as suggested by the static analysis tool:
- Line 52: "### Use the fetch function"
- Line 69: "Notice that only a few (highlighted) lines have been changed from the original, but now the fetch is type-safe."
Also applies to: 69-69
Tools
LanguageTool
[uncategorized] ~52-~52: You might be missing the article “the” here.
Context: ... GITHUB_API_ORIGIN, Spec>;### Use fetch functiontypescript {3} const GITHU...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
docs/docs/05_server/express.md (2)
38-38: Minor text improvement suggestionConsider adding the article "the" before "validation library" for better readability:
-Note that the validate method is depended on validation library you use. +Note that the validate method is depended on the validation library you use.Tools
LanguageTool
[uncategorized] ~38-~38: Possible missing article found.
Context: ...depended on validation library you use. Following example uses zod. ```typescript impor...(AI_HYDRA_LEO_MISSING_THE)
71-71: Minor text improvement suggestionsConsider adding the missing articles in this sentence for better readability:
-If error is thrown in async handler of wrapped app, it will be caught and passed to the error handler. +If an error is thrown in an async handler of the wrapped app, it will be caught and passed to the error handler.Tools
LanguageTool
[uncategorized] ~71-~71: Possible missing article found.
Context: ... to handle errors of async handlers. If error is thrown in async handler of wrapped a...(AI_HYDRA_LEO_MISSING_AN)
[uncategorized] ~71-~71: Possible missing article found.
Context: ...f async handlers. If error is thrown in async handler of wrapped app, it will be caug...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~71-~71: Possible missing article found.
Context: ... If error is thrown in async handler of wrapped app, it will be caught and passed to th...(AI_HYDRA_LEO_MISSING_A)
docs/docs/03_api_specification.md (1)
134-149: Consider adding a missing article.The "API" section provides a clear introduction to the
DefineApiEndpointsutility type and its purpose in enforcing type safety for API specifications. The code example effectively illustrates its usage. However, there is a small suggestion to improve the clarity of the explanation:
- Line 139: Consider adding the article "a" before "wrong API specification" to improve readability.
Apply the following change to enhance the clarity of the explanation:
-If you write wrong API specification, DefineApiEndpoints will throw a type error. +If you write a wrong API specification, DefineApiEndpoints will throw a type error.Tools
LanguageTool
[uncategorized] ~139-~139: Possible missing article found.
Context: ...nes the API specification. If you write wrong API specification, DefineApiEndpoints w...(AI_HYDRA_LEO_MISSING_THE)
docs/docs/04_client.md (1)
42-42: Address grammatical issues and missing articles.The LanguageTool static analysis tool has identified a few grammatical issues and missing articles in the documentation. Please consider applying the following fixes:
- Line 42: Fix the noun/verb agreement error.
-If the response have multiple status codes, response type is union of each status code type. +If the response has multiple status codes, the response type is a union of each status code type.
- Line 159: Add the missing article.
-FetchT is a type that adds type information to native fetch. First generic parameter is the origin of the API server, and the second generic parameter is the API specification. +FetchT is a type that adds type information to native fetch. The first generic parameter is the origin of the API server, and the second generic parameter is the API specification.Addressing these minor grammatical issues will further improve the clarity and readability of the documentation.
Also applies to: 159-159
Tools
LanguageTool
[grammar] ~42-~42: There seems to be a noun/verb agreement error. Did you mean “has” or “had”?
Context: ...rNames: string[] } ``` If the response have multiple status codes, response type is...(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...he response have multiple status codes, response type is union of each status code type....(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...multiple status codes, response type is union of each status code type. ```typescrip...(AI_HYDRA_LEO_MISSING_THE)
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files ignored due to path filters (3)
docs/docs/tutorial-extras/img/docsVersionDropdown.pngis excluded by!**/*.pngdocs/docs/tutorial-extras/img/localeDropdown.pngis excluded by!**/*.pngdocs/static/img/typed-api-spec.pngis excluded by!**/*.png
Files selected for processing (27)
- .idea/typed-api-spec.iml (1 hunks)
- docs/docs/01_overview.md (1 hunks)
- docs/docs/02_getting-started.md (1 hunks)
- docs/docs/03_api_specification.md (1 hunks)
- docs/docs/04_client.md (1 hunks)
- docs/docs/05_server/category.json (1 hunks)
- docs/docs/05_server/express.md (1 hunks)
- docs/docs/05_server/fastify.md (1 hunks)
- docs/docs/06_validation/category.json (1 hunks)
- docs/docs/06_validation/concept.md (1 hunks)
- docs/docs/06_validation/valibot.md (1 hunks)
- docs/docs/06_validation/write.md (1 hunks)
- docs/docs/06_validation/zod.md (1 hunks)
- docs/docs/intro.md (0 hunks)
- docs/docs/tutorial-basics/category.json (0 hunks)
- docs/docs/tutorial-basics/congratulations.md (0 hunks)
- docs/docs/tutorial-basics/create-a-blog-post.md (0 hunks)
- docs/docs/tutorial-basics/create-a-document.md (0 hunks)
- docs/docs/tutorial-basics/create-a-page.md (0 hunks)
- docs/docs/tutorial-basics/deploy-your-site.md (0 hunks)
- docs/docs/tutorial-basics/markdown-features.mdx (0 hunks)
- docs/docs/tutorial-extras/category.json (0 hunks)
- docs/docs/tutorial-extras/manage-docs-versions.md (0 hunks)
- docs/docs/tutorial-extras/translate-your-site.md (0 hunks)
- docs/docusaurus.config.ts (1 hunks)
- examples/github/github.ts (1 hunks)
- src/express/zod.ts (1 hunks)
Files not reviewed due to no reviewable changes (11)
- docs/docs/intro.md
- docs/docs/tutorial-basics/category.json
- docs/docs/tutorial-basics/congratulations.md
- docs/docs/tutorial-basics/create-a-blog-post.md
- docs/docs/tutorial-basics/create-a-document.md
- docs/docs/tutorial-basics/create-a-page.md
- docs/docs/tutorial-basics/deploy-your-site.md
- docs/docs/tutorial-basics/markdown-features.mdx
- docs/docs/tutorial-extras/category.json
- docs/docs/tutorial-extras/manage-docs-versions.md
- docs/docs/tutorial-extras/translate-your-site.md
Files skipped from review due to trivial changes (4)
- .idea/typed-api-spec.iml
- docs/docs/05_server/category.json
- docs/docs/06_validation/category.json
- docs/docusaurus.config.ts
Additional context used
LanguageTool
docs/docs/06_validation/valibot.md
[uncategorized] ~7-~7: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... valibot is the open source schema library for TypeScript with bund...(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/docs/01_overview.md
[uncategorized] ~7-~7: Use the indefinite article “a” before nouns that start with a consonant sound.
Context: ...n: 1 --- # Overview typed-api-spec is an TypeScript based declarative API specif...(AI_EN_LECTOR_REPLACEMENT_DETERMINER_AN_A)
[uncategorized] ~7-~7: This expression is usually spelled with a hyphen.
Context: ...1 --- # Overview typed-api-spec is an TypeScript based declarative API specification. ## Feat...(BASED_HYPHEN)
[uncategorized] ~11-~11: This expression is usually spelled with a hyphen.
Context: ...ve API specification. ## Features ### TypeScript based API Specification You can define your A...(BASED_HYPHEN)
docs/docs/02_getting-started.md
[uncategorized] ~52-~52: You might be missing the article “the” here.
Context: ... GITHUB_API_ORIGIN, Spec>;### Use fetch functiontypescript {3} const GITHU...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~69-~69: Possible missing article found.
Context: ...ghlighted) lines have been changed from original, but now the fetch is type-safe.(AI_HYDRA_LEO_MISSING_THE)
docs/docs/05_server/express.md
[uncategorized] ~38-~38: Possible missing article found.
Context: ...depended on validation library you use. Following example uses zod. ```typescript impor...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~71-~71: Possible missing article found.
Context: ... to handle errors of async handlers. If error is thrown in async handler of wrapped a...(AI_HYDRA_LEO_MISSING_AN)
[uncategorized] ~71-~71: Possible missing article found.
Context: ...f async handlers. If error is thrown in async handler of wrapped app, it will be caug...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~71-~71: Possible missing article found.
Context: ... If error is thrown in async handler of wrapped app, it will be caught and passed to th...(AI_HYDRA_LEO_MISSING_A)
docs/docs/03_api_specification.md
[grammar] ~81-~81: There seems to be a noun/verb agreement error. Did you mean “has” or “had”?
Context: ...; }; }; }; }; }>; ``` ### Spec Spec have the following properties: -params: T...(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~83-~83: Loose punctuation mark.
Context: ...ath parameters of the request. -query: The query parameters of the request. - ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~84-~84: Loose punctuation mark.
Context: ...y parameters of the request. -headers: The headers of the request. -body: T...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~85-~85: Loose punctuation mark.
Context: ...s: The headers of the request. -body: The body of the request. -responses`:...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~86-~86: Loose punctuation mark.
Context: ...: The body of the request. -responses: The response schema of the request. -...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~87-~87: Loose punctuation mark.
Context: ...sponse schema of the request. -body: The body of the response. -headers...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~88-~88: Loose punctuation mark.
Context: ... The body of the response. -headers: The headers of the response. ```type...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~139-~139: Possible missing article found.
Context: ...nes the API specification. If you write wrong API specification, DefineApiEndpoints w...(AI_HYDRA_LEO_MISSING_THE)
docs/docs/04_client.md
[grammar] ~42-~42: There seems to be a noun/verb agreement error. Did you mean “has” or “had”?
Context: ...rNames: string[] } ``` If the response have multiple status codes, response type is...(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...he response have multiple status codes, response type is union of each status code type....(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...multiple status codes, response type is union of each status code type. ```typescrip...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~159-~159: Possible missing article found.
Context: ... adds type information to native fetch. First generic parameter is the origin of the ...(AI_HYDRA_LEO_MISSING_THE)
Markdownlint
docs/docs/06_validation/valibot.md
30-30: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
docs/docs/02_getting-started.md
23-23: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
docs/docs/03_api_specification.md
10-10: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
Additional comments not posted (26)
docs/docs/06_validation/zod.md (1)
10-28: Great code example!The code example is well-structured and demonstrates how to use Zod to define an API specification for a user endpoint. It covers all the necessary aspects of the endpoint, including:
- Request parameters
- Query parameters
- Headers
- Response structure
This example serves as a good reference for users to understand how to use Zod with typed-api-spec.
docs/docs/06_validation/valibot.md (1)
1-33: Excellent documentation for Valibot!The documentation provides a clear and concise overview of Valibot and its features. The code example effectively demonstrates how to define an API specification using Valibot, making it easy for users to understand and get started with the library.
The mention of Express integration is also helpful for users looking to integrate Valibot with their server framework.
Overall, the documentation is well-structured, informative, and serves as a great resource for users interested in using Valibot for their API specifications.
Tools
LanguageTool
[uncategorized] ~7-~7: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... valibot is the open source schema library for TypeScript with bund...(EN_COMPOUND_ADJECTIVE_INTERNAL)
Markdownlint
30-30: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
docs/docs/05_server/fastify.md (4)
7-25: Great example of setting up a Fastify server withtyped-api-specandzod!The code snippet provides a clear and concise example of:
- Configuring a Fastify server with logging enabled
- Setting up validation and serialization compilers
- Using the
toRoutes()function to convert the API specification schema to Fastify route objects- Defining a GET route for fetching user names based on a query parameter
The route handler demonstrates how to access the query parameter and return a response.
35-58: Great example of using thetoRoutes()function!The code snippet provides a clear example of:
- Defining an API specification schema using
zod- Using the
toRoutes()function to convert the schema to Fastify route objects- Logging the output of the
toRoutes()function to show the structure of the generated route objectThis helps developers understand how to define the API specification schema and use the
toRoutes()function effectively.
29-31: The API documentation for thetoRoutes()function is clear and concise.The description accurately states the purpose of the function, which is to convert the API specification schema to Fastify route objects. This helps developers understand the role of the
toRoutes()function in the integration oftyped-api-specwith Fastify.
60-62: The "Supported validation libraries" section is informative and helpful.The section informs developers that
zodis a supported validation library, which is useful information. It also provides a convenient link to the documentation for usingzodwithtyped-api-spec, making it easy for developers to access further information if needed.examples/github/github.ts (4)
1-9: LGTM!The imports, constants, and types are correctly defined and used in the implementation.
11-38: Great work on the API specification!The
Spectype comprehensively defines the API specification for the endpoint/repos/:owner/:repo/topics, including the expected request structure and possible response formats. The specification is clear and well-structured.
39-39: Nice use of theFetchTutility type!The
fetchTconstant is correctly defined as a typed fetch wrapper, ensuring that requests to the GitHub API conform to the defined specifications. This enhances type safety when making API calls.
41-54: Excellent implementation of themainfunction!The
mainfunction correctly orchestrates the API call using thefetchTwrapper and handles the response appropriately. It demonstrates the usage of the typed API specification and fetch wrapper, ensuring type safety and clarity when interacting with the GitHub API.docs/docs/01_overview.md (1)
1-46: Excellent overview of the typed-api-spec project!The
01_overview.mdfile provides a clear and concise introduction to thetyped-api-specproject. The code snippets are well-formatted and provide useful examples of how to define API endpoints and use the typed fetch function. The file is well-structured and easy to follow.Great job on creating this comprehensive overview!
Tools
LanguageTool
[uncategorized] ~7-~7: Use the indefinite article “a” before nouns that start with a consonant sound.
Context: ...n: 1 --- # Overview typed-api-spec is an TypeScript based declarative API specif...(AI_EN_LECTOR_REPLACEMENT_DETERMINER_AN_A)
[uncategorized] ~7-~7: This expression is usually spelled with a hyphen.
Context: ...1 --- # Overview typed-api-spec is an TypeScript based declarative API specification. ## Feat...(BASED_HYPHEN)
[uncategorized] ~11-~11: This expression is usually spelled with a hyphen.
Context: ...ve API specification. ## Features ### TypeScript based API Specification You can define your A...(BASED_HYPHEN)
src/express/zod.ts (1)
54-55: LGTM!The destructuring assignment and subsequent error handling logic improve code readability and align with common practices in handling validation results. The change makes the error handling more explicit and reduces reliance on a success flag.
docs/docs/02_getting-started.md (4)
9-21: LGTM!The code snippet effectively demonstrates the limitations of fetching data from the GitHub API without type safety. It sets the stage for introducing the benefits of using the
@mpppk/typed-api-speclibrary.
31-43: LGTM!The code snippet effectively demonstrates how to define the API specification using the
DefineApiEndpointstype. The structured definition of the API endpoints, including the query parameters and response formats, enhances type safety and clarity.
54-67: LGTM!The code snippet effectively demonstrates the usage of the
fetchTfunction to make a type-safe API call. The type-safe response handling based on the success or failure of the request is a significant improvement over the non-type-safe approach. The code clearly illustrates the benefits of using the@mpppk/typed-api-speclibrary.
1-69: Excellent documentation!The documentation provides a comprehensive and well-structured guide for integrating the
@mpppk/typed-api-speclibrary into an npm project. The explanations are clear, and the code snippets effectively demonstrate each step of the process. The documentation successfully highlights the benefits of using the library for type-safe API interactions.Tools
LanguageTool
[uncategorized] ~52-~52: You might be missing the article “the” here.
Context: ... GITHUB_API_ORIGIN, Spec>;### Use fetch functiontypescript {3} const GITHU...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~69-~69: Possible missing article found.
Context: ...ghlighted) lines have been changed from original, but now the fetch is type-safe.(AI_HYDRA_LEO_MISSING_THE)
Markdownlint
23-23: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
docs/docs/06_validation/concept.md (4)
12-34: LGTM!The code segment demonstrates a clear and effective way to define an API specification using TypeScript types and the
zodvalidation library. By separating runtime validation from API definition, it allows developers to use any validation library of their choice while still benefiting from the type safety provided bytyped-api-spec. The code is well-structured and follows best practices.
39-44: Good example, but be cautious of using the correct schema.The code segment demonstrates how to perform runtime validation of request parameters using the
zodschema defined earlier. This is a good practice to validate incoming data and prevent potential errors or security vulnerabilities.However, as mentioned in the document, there is no guarantee that the
UsersQueryschema is actually the expected schema for the specific endpoint. Developers may accidentally use the wrong schema, leading to potential issues. It's important to ensure that the correct schema is used for each endpoint to maintain consistency and avoid validation errors.
51-62: Excellent approach to define API specification with integrated validation!The code segment demonstrates an alternative approach to defining an API specification using
zodschemas directly, without separating the validation from the API definition. By defining theSpecobject usingzodschemas for the query parameters and response body, it ensures that the API specification itself is validated against the expected structure.This approach provides several benefits:
- It is more concise and integrated, reducing the chances of using the wrong schema for a specific endpoint.
- The
satisfies ZodApiEndpointsstatement ensures that theSpecobject conforms to the expected structure, providing an additional layer of type safety.- The code is well-structured and follows best practices, making it easier to understand and maintain.
Overall, this approach is a great way to define API specifications with integrated validation, enhancing the reliability and maintainability of the application.
66-71: Great usage of theSpecobject for runtime validation!The code segment demonstrates how to utilize the
Specobject defined earlier to perform runtime validation of request parameters in an Express route handler. By accessing the specific endpoint and HTTP method from theSpecobject and using theparsemethod, it ensures that the query parameters conform to the expected structure and types defined in the API specification.This approach provides several benefits:
- It is more type-safe and integrated, as it directly uses the schemas defined in the API specification.
- It reduces the chances of using the wrong schema and ensures consistency between the API specification and the actual validation performed in the route handler.
- The code is clear and concise, making it easy to understand and maintain.
Overall, this approach showcases the power of using the
Specobject for runtime validation, enhancing the reliability and maintainability of the application.docs/docs/05_server/express.md (1)
1-83: Excellent documentation for integrating Express withtyped-api-spec!The guide provides a clear and comprehensive explanation of how to use the
typed()function to apply strict types to an Express app, and how to use thevalidate()method to validate request parameters. The code snippets effectively demonstrate the usage and integration with validation libraries likezod.The inclusion of the
asAsync()function for handling async errors in Express 4 or lower is a helpful addition, with a clear note about its necessity and the upcoming support in Express 5.Overall, this documentation file serves as a valuable resource for developers looking to implement type-safe APIs with Express and
typed-api-spec. Great work!Tools
LanguageTool
[uncategorized] ~38-~38: Possible missing article found.
Context: ...depended on validation library you use. Following example uses zod. ```typescript impor...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~71-~71: Possible missing article found.
Context: ... to handle errors of async handlers. If error is thrown in async handler of wrapped a...(AI_HYDRA_LEO_MISSING_AN)
[uncategorized] ~71-~71: Possible missing article found.
Context: ...f async handlers. If error is thrown in async handler of wrapped app, it will be caug...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~71-~71: Possible missing article found.
Context: ... If error is thrown in async handler of wrapped app, it will be caught and passed to th...(AI_HYDRA_LEO_MISSING_A)
docs/docs/03_api_specification.md (3)
38-56: LGTM!The "Structure" section provides a clear explanation of the API specification structure and includes a relevant code example to illustrate the usage. The content is well-organized and easy to understand.
58-77: LGTM!The "Method" section provides a complete list of supported HTTP methods and includes a clear code example to demonstrate defining endpoints with different methods. The content is well-structured and informative.
106-132: LGTM!The "Validation library integration" section provides a clear explanation of how typed-api-spec can be integrated with validation libraries like Zod. The code example effectively demonstrates defining request and response schemas using Zod, ensuring type safety and validation. The content is well-structured and informative.
docs/docs/04_client.md (2)
1-178: Excellent documentation!The documentation provides a clear and comprehensive guide on using
zero-fetchfor type-safe API interactions. The explanation of the "zero-runtime" concept and howzero-fetchadds type information to the native fetch without increasing the runtime footprint or bundle size is well-written and easy to understand.The various type-safe features such as response, path, path parameters, query, headers, and body are thoroughly covered, and the TypeScript code examples effectively demonstrate the usage and features of
zero-fetch.The API section provides clear information on the usage of
FetchTandJSONTtypes.Overall, the documentation content is well-structured, informative, and easy to follow. Great job!
Tools
LanguageTool
[grammar] ~42-~42: There seems to be a noun/verb agreement error. Did you mean “has” or “had”?
Context: ...rNames: string[] } ``` If the response have multiple status codes, response type is...(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...he response have multiple status codes, response type is union of each status code type....(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~42-~42: Possible missing article found.
Context: ...multiple status codes, response type is union of each status code type. ```typescrip...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~159-~159: Possible missing article found.
Context: ... adds type information to native fetch. First generic parameter is the origin of the ...(AI_HYDRA_LEO_MISSING_THE)
15-18: Code examples are accurate and effective!The TypeScript code examples in the documentation are well-written and effectively demonstrate the usage and features of
zero-fetch. The examples cover various scenarios such as defining API specifications, handling response types, path and path parameters, query parameters, headers, and request body.The examples correctly use the
FetchTandJSONTtypes to provide type safety, and they include error cases to showcase howzero-fetchenforces type safety at compile time.The code examples follow best practices, are concise, and focused on demonstrating specific features. There are no apparent issues or errors in the code examples.
Great work on providing clear and accurate code examples to support the documentation!
Also applies to: 28-40, 44-70, 77-93, 99-112, 118-131, 138-153, 162-164, 171-176
| # Write your own integration | ||
|
|
||
| If you want to use a validation library which is not supported by `typed-api-spec`, you can write your own integration. | ||
| typed-api-spec provides a utility type `DefineApiSpec`, `DefineApiResponses`, and others for defining API specification schema with validation library. | ||
|
|
||
| TBW No newline at end of file |
There was a problem hiding this comment.
Complete the documentation with more details and examples.
The documentation provides a good starting point for guiding developers on writing custom integrations for validation libraries. However, it is currently incomplete and lacks important details:
-
Provide more information on the utility types (
DefineApiSpec,DefineApiResponses, etc.):- Explain their purpose and how they facilitate defining API specification schemas.
- Describe their usage and provide code examples.
-
Expand the "TBW" section with the necessary content:
- Provide step-by-step instructions on how to write a custom integration.
- Include code snippets and examples to illustrate the process.
- Explain how to use the utility types in conjunction with the validation library.
-
Consider adding a section on best practices and common pitfalls to help developers avoid mistakes when writing custom integrations.
Completing the documentation with these details will greatly improve its usefulness and help developers effectively write custom integrations for validation libraries.
docs/docs/02_getting-started.md
Outdated
| console.log(names); // => ["api-spec", "fetch", "typescript"] | ||
| ``` | ||
|
|
||
| ### Installation |
There was a problem hiding this comment.
Fix the heading level.
The heading level should only increment by one level at a time. Change the heading level of "### Installation" to "## Installation" to maintain a consistent heading hierarchy.
Tools
Markdownlint
23-23: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
| ### Spec | ||
|
|
||
| Spec have the following properties: | ||
| - `params`: The path parameters of the request. | ||
| - `query`: The query parameters of the request. | ||
| - `headers`: The headers of the request. | ||
| - `body`: The body of the request. | ||
| - `responses`: The response schema of the request. | ||
| - `body`: The body of the response. | ||
| - `headers`: The headers of the response. | ||
|
|
||
| ```typescript | ||
| type Spec = DefineApiEndpoints<{ | ||
| "/users/:id": { | ||
| get: { | ||
| params: { id: string }; | ||
| query: { page?: string }; | ||
| headers: { "x-api-key": string }; | ||
| responses: { 200: { | ||
| headers: {"content-type": "application/json"}; | ||
| body: { userNames: string[] }; }; | ||
| }; | ||
| }; | ||
| }; | ||
| }>; | ||
| ``` |
There was a problem hiding this comment.
Address grammatical and punctuation issues.
The "Spec" section provides a comprehensive explanation of the Spec properties and includes a relevant code example. However, there are a few issues that need attention:
- Line 81: There seems to be a noun/verb agreement error. Consider changing "have" to "has" to match the singular noun "Spec".
- Lines 83-88: The punctuation marks (backticks) before the property names appear to be loose. Consider removing the spaces before the backticks for consistency.
Apply the following changes to improve the clarity and readability of the content:
-Spec have the following properties:
+Spec has the following properties:
- `params`: The path parameters of the request.
+ `params`: The path parameters of the request.
- `query`: The query parameters of the request.
+ `query`: The query parameters of the request.
- `headers`: The headers of the request.
+ `headers`: The headers of the request.
- `body`: The body of the request.
+ `body`: The body of the request.
- `responses`: The response schema of the request.
+ `responses`: The response schema of the request.
- `body`: The body of the response.
- `headers`: The headers of the response.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Spec | |
| Spec have the following properties: | |
| - `params`: The path parameters of the request. | |
| - `query`: The query parameters of the request. | |
| - `headers`: The headers of the request. | |
| - `body`: The body of the request. | |
| - `responses`: The response schema of the request. | |
| - `body`: The body of the response. | |
| - `headers`: The headers of the response. | |
| ```typescript | |
| type Spec = DefineApiEndpoints<{ | |
| "/users/:id": { | |
| get: { | |
| params: { id: string }; | |
| query: { page?: string }; | |
| headers: { "x-api-key": string }; | |
| responses: { 200: { | |
| headers: {"content-type": "application/json"}; | |
| body: { userNames: string[] }; }; | |
| }; | |
| }; | |
| }; | |
| }>; | |
| ``` | |
| ### Spec | |
| Spec has the following properties: | |
| `params`: The path parameters of the request. | |
| `query`: The query parameters of the request. | |
| `headers`: The headers of the request. | |
| `body`: The body of the request. | |
| `responses`: The response schema of the request. | |
| - `body`: The body of the response. | |
| - `headers`: The headers of the response. | |
| ```typescript | |
| type Spec = DefineApiEndpoints<{ | |
| "/users/:id": { | |
| get: { | |
| params: { id: string }; | |
| query: { page?: string }; | |
| headers: { "x-api-key": string }; | |
| responses: { 200: { | |
| headers: {"content-type": "application/json"}; | |
| body: { userNames: string[] }; }; | |
| }; | |
| }; | |
| }; | |
| }>; | |
| ``` |
Tools
LanguageTool
[grammar] ~81-~81: There seems to be a noun/verb agreement error. Did you mean “has” or “had”?
Context: ...; }; }; }; }; }>; ``` ### Spec Spec have the following properties: -params: T...(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~83-~83: Loose punctuation mark.
Context: ...ath parameters of the request. -query: The query parameters of the request. - ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~84-~84: Loose punctuation mark.
Context: ...y parameters of the request. -headers: The headers of the request. -body: T...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~85-~85: Loose punctuation mark.
Context: ...s: The headers of the request. -body: The body of the request. -responses`:...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~86-~86: Loose punctuation mark.
Context: ...: The body of the request. -responses: The response schema of the request. -...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~87-~87: Loose punctuation mark.
Context: ...sponse schema of the request. -body: The body of the response. -headers...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~88-~88: Loose punctuation mark.
Context: ... The body of the response. -headers: The headers of the response. ```type...(UNLIKELY_OPENING_PUNCTUATION)
There was a problem hiding this comment.
Actionable comments posted: 0
Outside diff range and nitpick comments (1)
docs/docs/03_api_specification.md (1)
149-149: Reminder: Address the TODO comment.The TODO comment indicates that a StackBlitz demo is planned to be added. This is a helpful addition to provide an interactive example for readers. Please ensure that the TODO comment is addressed in a timely manner.
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (2)
- docs/docs/02_getting-started.md (1 hunks)
- docs/docs/03_api_specification.md (1 hunks)
Additional context used
LanguageTool
docs/docs/02_getting-started.md
[uncategorized] ~52-~52: You might be missing the article “the” here.
Context: ...f GITHUB_API_ORIGIN, Spec>;## Use fetch functiontypescript {3} const GITHU...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~69-~69: You might be missing the article “a” here.
Context: ...h", "typescript"] ``` Notice that only few (highlighted) lines have been changed f...(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~69-~69: You might be missing the article “the” here.
Context: ...ghlighted) lines have been changed from original, but now the fetch is type-safe.(AI_EN_LECTOR_MISSING_DETERMINER_THE)
docs/docs/03_api_specification.md
[uncategorized] ~83-~83: Loose punctuation mark.
Context: ...ath parameters of the request. -query: The query parameters of the request. - ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~84-~84: Loose punctuation mark.
Context: ...y parameters of the request. -headers: The headers of the request. -body: T...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~85-~85: Loose punctuation mark.
Context: ...s: The headers of the request. -body: The body of the request. -responses`:...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~86-~86: Loose punctuation mark.
Context: ...: The body of the request. -responses: The response schema of the request. -...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~87-~87: Loose punctuation mark.
Context: ...sponse schema of the request. -body: The body of the response. -headers...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~88-~88: Loose punctuation mark.
Context: ... The body of the response. -headers: The headers of the response. ```type...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~139-~139: Possible missing article found.
Context: ...nes the API specification. If you write wrong API specification, DefineApiEndpoints w...(AI_HYDRA_LEO_MISSING_THE)
Markdownlint
docs/docs/03_api_specification.md
10-10: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
Additional comments not posted (6)
docs/docs/02_getting-started.md (2)
1-69: Excellent documentation!The new "Getting Started" documentation file provides a comprehensive and easy-to-follow guide for integrating the
@mpppk/typed-api-speclibrary into an npm project. The examples and explanations effectively demonstrate the benefits of using the library, particularly in terms of enhancing type safety in API interactions.The file is well-structured, with clear sections covering installation, defining API specs, adding types to the fetch function, and using the typed fetch function. The code snippets and accompanying explanations are concise and informative, making it easy for developers to understand and apply the concepts.
Overall, this documentation serves as an essential resource for developers looking to leverage the
@mpppk/typed-api-speclibrary in their projects. Great work!Tools
LanguageTool
[uncategorized] ~52-~52: You might be missing the article “the” here.
Context: ...f GITHUB_API_ORIGIN, Spec>;## Use fetch functiontypescript {3} const GITHU...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~69-~69: You might be missing the article “a” here.
Context: ...h", "typescript"] ``` Notice that only few (highlighted) lines have been changed f...(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~69-~69: You might be missing the article “the” here.
Context: ...ghlighted) lines have been changed from original, but now the fetch is type-safe.(AI_EN_LECTOR_MISSING_DETERMINER_THE)
23-23: The heading level issue has been resolved.The heading level for "Installation" has been correctly set to
##, maintaining a consistent heading hierarchy throughout the document. The past review comment regarding this issue is no longer applicable.docs/docs/03_api_specification.md (4)
5-37: LGTM!The "API Specification" section provides a clear and concise introduction to the API specification structure. The code example accurately demonstrates the structure of Path, Method, and Spec components.
Tools
Markdownlint
10-10: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
38-104: LGTM!The "Structure" section provides a comprehensive explanation of the Path, Method, and Spec components. The code examples accurately demonstrate the usage of each component. The supported HTTP methods and the properties of the Spec component are clearly listed.
Tools
LanguageTool
[uncategorized] ~83-~83: Loose punctuation mark.
Context: ...ath parameters of the request. -query: The query parameters of the request. - ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~84-~84: Loose punctuation mark.
Context: ...y parameters of the request. -headers: The headers of the request. -body: T...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~85-~85: Loose punctuation mark.
Context: ...s: The headers of the request. -body: The body of the request. -responses`:...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~86-~86: Loose punctuation mark.
Context: ...: The body of the request. -responses: The response schema of the request. -...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~87-~87: Loose punctuation mark.
Context: ...sponse schema of the request. -body: The body of the response. -headers...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~88-~88: Loose punctuation mark.
Context: ... The body of the response. -headers: The headers of the response. ```type...(UNLIKELY_OPENING_PUNCTUATION)
106-132: LGTM!The "Validation library integration" section provides a clear explanation of the integration with validation libraries. The code example accurately demonstrates the usage of Zod for schema validation. The reference to the "Validation" page is helpful for readers who want to learn more about the topic.
134-147: LGTM!The "API" section provides a clear introduction to the
DefineApiEndpointsutility type. The explanation of its purpose and behavior is accurate. The code example demonstrates the usage ofDefineApiEndpointscorrectly.Tools
LanguageTool
[uncategorized] ~139-~139: Possible missing article found.
Context: ...nes the API specification. If you write wrong API specification, DefineApiEndpoints w...(AI_HYDRA_LEO_MISSING_THE)
Summary by CodeRabbit
New Features
typed-api-speclibrary, covering API specifications, integration with various frameworks, and type-safe API interactions.zero-fetchand validation libraries like Zod and Valibot.Bug Fixes
Chores