From 105ce7738745dd6eaeb20210e2fa1cf160fd2d69 Mon Sep 17 00:00:00 2001 From: Nicolas Froidure Date: Sun, 19 Jun 2022 09:27:35 +0200 Subject: [PATCH] fix(docs): fix various doc issues --- packages/whook-aws-lambda/README.md | 14 ++++----- packages/whook-gcp-functions/README.md | 11 +++---- packages/whook-graphiql/README.md | 6 ++-- packages/whook-graphql/README.md | 10 +++--- .../whook-graphql/src/handlers/postGraphQL.ts | 3 +- .../whook-graphql/src/services/graphQL.ts | 2 +- packages/whook-oauth2/README.md | 31 +++++++++++-------- packages/whook-swagger-ui/README.md | 24 +++++++------- 8 files changed, 54 insertions(+), 47 deletions(-) diff --git a/packages/whook-aws-lambda/README.md b/packages/whook-aws-lambda/README.md index 063294d5..c86c2644 100644 --- a/packages/whook-aws-lambda/README.md +++ b/packages/whook-aws-lambda/README.md @@ -20,20 +20,20 @@ You can find a complete setup with a Terraform deployment example in ## Quick setup -Install this module and its peer dependencies : +Install this module: ```sh npm i @whook/aws-lambda; -npm i --save-dev @whook/http-transaction esbuild ``` Add this module to your Whook plugins and tweak the 2 build functions in your -`build.ts` main file: +`src/build.ts` main file: ```diff import { // (...) - runBuild as runBaseBuild, +- prepareBuildEnvironment as prepareBaseBuildEnvironment, // (...) } from '@whook/whook'; +import { @@ -155,7 +155,7 @@ export default CONFIG; # Build -To build your functions : +To build your functions: ```sh # Build all functions @@ -167,7 +167,7 @@ npm run build -- getPing # Debug -You can easily test your function builds by adding `@whook/aws-lambda` to your +You can easily test your functions builds by adding `@whook/aws-lambda` to your `WHOOK_PLUGINS` list. It provides you some commands like the `testHTTPLambda` one: @@ -175,10 +175,10 @@ one: npx whook testHTTPLambda --name getPing ``` -To get more insights when errors happens: +To get more insights when some errors happens: ```sh -npm run whook-dev -- testHTTPLambda --name getPing +DEBUG=whook npm run whook-dev -- testHTTPLambda --name getPing ``` ## Deployment diff --git a/packages/whook-gcp-functions/README.md b/packages/whook-gcp-functions/README.md index 8c580918..08ce842c 100644 --- a/packages/whook-gcp-functions/README.md +++ b/packages/whook-gcp-functions/README.md @@ -21,15 +21,14 @@ You can find a complete setup with a Terraform deployment example in ## Quick setup -Install this module and its peer dependencies : +Install this module: ```sh npm i @whook/gcp-functions; -npm i --save-dev @whook/http-transaction esbuild ``` Add this module to your Whook plugins and tweak the 2 build functions in your -`build.ts` main file: +`src/build.ts` main file: ```diff import { @@ -155,7 +154,7 @@ export default CONFIG; # Build -To build your functions : +To build your functions: ```sh # Build all functions @@ -175,10 +174,10 @@ your `WHOOK_PLUGINS` list. It provides you some commands like the npx whook testHTTPFunction --name getPing ``` -To get more insights when errors happens: +To get more insights when some errors happens: ```sh -npm run whook-dev -- testHTTPFunction --name getPing +DEBUG=whook npm run whook-dev -- testHTTPFunction --name getPing ``` ## Deployment diff --git a/packages/whook-graphiql/README.md b/packages/whook-graphiql/README.md index 3c5f44ee..5e877560 100644 --- a/packages/whook-graphiql/README.md +++ b/packages/whook-graphiql/README.md @@ -18,7 +18,7 @@ This module provides the GraphIQL UI to your local ## Usage The `DEV_MODE=1` environment variable must be used when starting your server -(`npm run dev` does it by default). +(the `npm run dev` script of default Whook projects does it by default). ## Setup @@ -32,9 +32,9 @@ Update the types (usually in `src/whook.d.ts`): ```diff +import type { -+ WhookGraphIQLEnv ++ WhookGraphIQLEnv, + WhookGraphIQLConfig, -+} from '@whook/swagger-ui'; ++} from '@whook/graphiql'; // ... diff --git a/packages/whook-graphql/README.md b/packages/whook-graphql/README.md index 90a6e5a2..c216c383 100644 --- a/packages/whook-graphql/README.md +++ b/packages/whook-graphql/README.md @@ -14,12 +14,12 @@ Brings GraphQL to your [Whook](https://github.com/nfroidure/whook) server! -This module uses [Apollo](https://www.apollographql.com/) under the hood most of +This module uses [Apollo](https://www.apollographql.com/) under the hood. Most of its concepts (modules, plugins...) applies to it. ## Quick setup -Install the module in your project: +Install the module and its dependencies in your project: ```sh npm i @whook/graphql apollo-server-core @@ -29,9 +29,9 @@ Update the types (usually in `src/whook.d.ts`): ```diff +import type { -+ WhookGraphQLEnv ++ WhookGraphQLEnv, + WhookGraphQLConfig, -+} from '@whook/swagger-ui'; ++} from '@whook/graphql'; // ... @@ -56,7 +56,7 @@ declare module '@whook/whook' { } ``` -Declare the plugin into your `index.ts` file: +Declare the plugin into your `src/index.ts` file: ```diff + import { gql } from 'apollo-server-core'; diff --git a/packages/whook-graphql/src/handlers/postGraphQL.ts b/packages/whook-graphql/src/handlers/postGraphQL.ts index 6c3a36ff..75ce1805 100644 --- a/packages/whook-graphql/src/handlers/postGraphQL.ts +++ b/packages/whook-graphql/src/handlers/postGraphQL.ts @@ -1,12 +1,13 @@ import { autoHandler } from 'knifecycle'; import { YHTTPError } from 'yhttperror'; -import { noop, WhookHeaders } from '@whook/whook'; +import { noop } from '@whook/whook'; import { Headers } from 'apollo-server-env'; import { runHttpQuery } from 'apollo-server-core'; import type { WhookAPIHandlerDefinition, WhookOperation, WhookResponse, + WhookHeaders, } from '@whook/whook'; import type { LogService } from 'common-services'; import type { WhookGraphQLService } from '../index.js'; diff --git a/packages/whook-graphql/src/services/graphQL.ts b/packages/whook-graphql/src/services/graphQL.ts index 408c96e1..4cae6906 100644 --- a/packages/whook-graphql/src/services/graphQL.ts +++ b/packages/whook-graphql/src/services/graphQL.ts @@ -17,7 +17,7 @@ export type WhookGraphQLFragmentService = { }; export type WhookGraphQLEnv = { - DEV_MODE: string; + DEV_MODE?: string; }; export type WhookGraphQLConfig = { GRAPHQL_SERVER_OPTIONS?: Config; diff --git a/packages/whook-oauth2/README.md b/packages/whook-oauth2/README.md index 0e5d7390..b23a4ecc 100644 --- a/packages/whook-oauth2/README.md +++ b/packages/whook-oauth2/README.md @@ -19,18 +19,21 @@ authenticate and allow client applications to act on behalf of them. ![Code Flow Overview](./code_flow_overview.svg) -The module provides : +The module provides: -- 3 handlers : the 2 OAuth2 standard endpoints (`getOAuth2authorize` and - `postOAuth2Tokentoken`) plus the `postOAuth2Acknowledge` to be used by the SSR - frontend, -- the 5 OAuth2 standard grant types implemented through plug and play services. - You can create your own granter services to create additional grant types. +- 2 OAuth2 handlers implementing the 2 OAuth2 standard endpoints + (`getOAuth2authorize`, `postOAuth2Tokentoken`) to be used by OAuth2 client + applications, +- 4 authentication endpoints to be used by the authorization server directly to + authenticate users (`postAuthLogin`, `postAuthRefresh`, `postAuthLogout`) and + acknowledge the client requests (`postOAuth2Acknowledge`), +- 5 OAuth2 services implementing the standard grant types. You can create your + own granter services to create additional grant types. This module requires you to implement some services it relies on: - `oAuth2AccessToken` that generates and checks the `access_token` and the - `oAuth2RefreshToken` for the `refresh_token` both have the same interface, + `oAuth2RefreshToken` for the `refresh_token`, both have the same interface, - `checkApplication` service that is supposed to check whether an application can be used or not for a given grant type, a given scope and redirect URI, - `oAuth2PasswordService` aimed to check the `password` grant type with your own @@ -48,7 +51,7 @@ Install the module in your project: npm i @whook/oauth2 ``` -Declare the plugin into your `index.ts` file: +Declare the plugin into your `src/index.ts` file: ```diff // (...) @@ -123,7 +126,7 @@ The `oAuth2Granters` service gather the various granters services you can use in your application but you can write your own that uses a subset or a superset of these granters. -Here, for example an handler that implement a verify token mechanism in order to +Here, for example a handler that implement a verify token mechanism in order to validate a user subscription: ```ts @@ -259,15 +262,16 @@ export default initPostAuthRefresh; ``` Additionnaly, you could create any handler in the `/auth` path in order to -receive the auth cookies. +receive the auth cookies. For example, you may want to serve user profiles +there. ## Customizing handlers The endpoints definitions are designed to support the standard OAuth2 definitions but can be easily overriden. -You will have to protect the `postOAuth2Acknowledge` with your own security -mechanism : +You will also have to protect the `postOAuth2Acknowledge` with your own security +mechanism: ```ts import { @@ -283,6 +287,7 @@ export const definition: WhookAPIHandlerDefinition = { ...postOAuth2AcknowledgeDefinition, operation: { ...postOAuth2AcknowledgeDefinition.operation, + // Complete the definition to protect the endpoint security: [ { bearerAuth: ['user'], @@ -331,7 +336,7 @@ export const definition: WhookAPIHandlerDefinition = { ``` You will probably need to also protect the `postOAuth2Token` endpoint with your -own security mecanism : +own security mecanism: ```ts // In a `src/handlers/postOAuth2Token.ts` fileimport { diff --git a/packages/whook-swagger-ui/README.md b/packages/whook-swagger-ui/README.md index 6a6cd69a..baca6f8b 100644 --- a/packages/whook-swagger-ui/README.md +++ b/packages/whook-swagger-ui/README.md @@ -13,24 +13,25 @@ [//]: # (::contents:start) This module provides the GraphIQL UI to your local - [Whook](https://github.com/nfroidure/whook) server ! +[Whook](https://github.com/nfroidure/whook) server ! ## Usage -The `DEV_MODE=1` environment variable must be used - when starting your server (`npm run dev` does it - by default). +The `DEV_MODE=1` environment variable must be used when starting your server +(`npm run dev` does it by default). ## Setup Install the module: + ```sh npm i @whook/swagger-ui ``` -To use it, just wrap the HTTP router with this module and - register it again with the `Knifecycle` instance inside the - `runServer` function (usually in `src/index.ts`): +To use it, just wrap the HTTP router with this module and override its +registration with the `Knifecycle` instance inside the `runServer` function +(usually in `src/index.ts`): + ```diff + import initHTTPRouter from '@whook/http-router'; + import wrapHTTPRouterWithSwaggerUI from '@whook/swagger-ui'; @@ -53,11 +54,11 @@ export async function runServer(injectedNames = [], $ = new Knifecycle()) { } ``` -Declare this module types in your `src/whook.d.ts` type - definitions: +Declare this module types in your `src/whook.d.ts` type definitions: + ```diff +import type { -+ WhookSwaggerUIEnv ++ WhookSwaggerUIEnv, + WhookAPIOperationSwaggerConfig, + WhookSwaggerUIConfig, +} from '@whook/swagger-ui'; @@ -69,7 +70,7 @@ declare module '@whook/whook' { // (...) + WhookGraphIQLEnv, WhookSwaggerUIEnv {} - + // ... export interface WhookConfigs @@ -96,6 +97,7 @@ declare module '@whook/whook' { ``` And add the SwaggerUI config (usually in `src/config/common/config.js`): + ```diff import type { WhookConfigs } from '@whook/whook';