From 55625e843149cc255692506570658e46bf2b4387 Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Fri, 21 May 2021 15:14:51 +0800 Subject: [PATCH 1/4] fix(apim): change swagger-jsdoc part in README file --- .../templates/plugins/resource/apim/README.md | 137 +++++++++++------- 1 file changed, 86 insertions(+), 51 deletions(-) diff --git a/packages/fx-core/templates/plugins/resource/apim/README.md b/packages/fx-core/templates/plugins/resource/apim/README.md index 442258f58f..297b39386a 100644 --- a/packages/fx-core/templates/plugins/resource/apim/README.md +++ b/packages/fx-core/templates/plugins/resource/apim/README.md @@ -53,57 +53,7 @@ In the deployment step, there will be some inputs needed: Update the Open API document under the `openapi` folder. We support both yaml and json format for the Open API document. You need to author the Open API document and ensure the API schema is aligned with the function implementation. For how to generate the Open API document, we have the following recommendations. -### Recommended way 1: Using npm package swagger-jsdoc - -- Run command: `npm install -g swagger-jsdoc`. -- Annotating source code. Read [more](https://github.com/Surnet/swagger-jsdoc/) about how to use swagger-jsdoc to annotate the source code. Below is a sample annotation. - - API annotation - ```js - /** - * @openapi - * /getUserProfile: - * get: - * summary: Get User Profile - * operationId: get-user-profile - * responses: - * '200': - * $ref: "#/components/responses/getUserProfileResponse" - */ - ``` - - Response annotation - ```js - /** - * @openapi - * components: - * responses: - * getUserProfileResponse: - * description: 200 response - * content: - * application/json: - * schema: - * type: object - * properties: - * receivedHTTPRequestBody: - * type: string - * userInfoMessage: - * type: string - * graphClientMessage: - * type: object - */ - ``` -- Create an OpenAPI definition file `openapi/openapi.definition.json` and input the title and version. Below is a sample definition file. - ```json - { - "openapi": "3.0.1", - "info": { - "title": "{appName}", - "version": "v1" - } - } - ``` -- Run command `swagger-jsdoc -d ./openapi/openapi.definition.json -o ./openapi/openapi.json ./api/getUserProfile/*`. Please change the file path `./api/getUserProfile/*` according to your modification. - -### Recommended way 2: OpenAPI (Swagger) Editor in VS Code. +### Recommended way 1: OpenAPI (Swagger) Editor in VS Code. Below is a sample swagger file for the default http trigger function. You can copy the content into `./openapi/openapi.json`, follow the [OpenAPI Specification](https://swagger.io/resources/open-api/), and change the content according to your modification (E.g. `/getUserProfile` -> `/$yourFunctionName` ). @@ -148,6 +98,91 @@ Below is a sample swagger file for the default http trigger function. You can co } ``` +### Recommended way 2: Using npm package swagger-jsdoc +- Annotating source code. Read [more](https://github.com/Surnet/swagger-jsdoc/) about how to use swagger-jsdoc to annotate the source code. Below is a sample annotation. + - API annotation + ```js + /** + * @openapi + * /getUserProfile: + * get: + * summary: Get User Profile + * operationId: get-user-profile + * responses: + * '200': + * $ref: "#/components/responses/getUserProfileResponse" + */ + ``` + - Response annotation + ```js + /** + * @openapi + * components: + * responses: + * getUserProfileResponse: + * description: 200 response + * content: + * application/json: + * schema: + * type: object + * properties: + * receivedHTTPRequestBody: + * type: string + * userInfoMessage: + * type: string + * graphClientMessage: + * type: object + */ + ``` +- Use swagger-jsdoc to generate OpenAPI document. Below is an example, you can learn more from [here](https://github.com/Surnet/swagger-jsdoc/tree/v7/examples/cli). + - Create an configuration `openapi/openapi.config.json` and input the title and version. Below is a sample definition file. Please change the file path `./api/getUserProfile/*` according to your modification. + ```json + { + "swaggerDefinition": { + "openapi": "3.0.1", + "info": { + "title": "{appName}", + "version": "v1" + } + }, + "apis": ["../api/getUserProfile/*"] + } + ``` + - Create `openapi/package.json` with content below. + ```json + { + "name": "swagger-jsdoc-generator", + "description": "Using swagger-jsdoc to generate OpenAPI", + "version": "0.0.1", + "type": "module", + "dependencies": { + "fs-extra": "^10.0.0", + "swagger-jsdoc": "^7.0.0-rc.6" + }, + "scripts": { + "generate": "npm install & node ./index.js" + } + } + ``` + - Create `openapi/index.js` with the content below. + ```js + import swaggerJSDoc from 'swagger-jsdoc'; + import fs from "fs-extra"; + + export default async function cli() { + const configFilePath = 'openapi.config.json'; + const swaggerFilePath = 'openapi.json'; + + const options = await fs.readJson(configFilePath); + const swaggerSpec = await swaggerJSDoc(options); + await fs.writeJson(swaggerFilePath, swaggerSpec, { spaces: 2 }); + } + + cli(); + ``` + - Run command `cd openapi`. + - Generate OpenAPI document `openapi/openapi.json`. Run command `npm run generate`. + ## Documentation Find help in [troubleshooting guide](https://aka.ms/teamsfx-apim-help) if you met any issues. From eeaddab1c2c1cc6b8493fbfebf9095c07ab1ddf3 Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Fri, 21 May 2021 15:25:48 +0800 Subject: [PATCH 2/4] fix(apim): update openapi/index.js --- .../fx-core/templates/plugins/resource/apim/README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/packages/fx-core/templates/plugins/resource/apim/README.md b/packages/fx-core/templates/plugins/resource/apim/README.md index 297b39386a..499ac734f3 100644 --- a/packages/fx-core/templates/plugins/resource/apim/README.md +++ b/packages/fx-core/templates/plugins/resource/apim/README.md @@ -169,13 +169,10 @@ Below is a sample swagger file for the default http trigger function. You can co import swaggerJSDoc from 'swagger-jsdoc'; import fs from "fs-extra"; - export default async function cli() { - const configFilePath = 'openapi.config.json'; - const swaggerFilePath = 'openapi.json'; - - const options = await fs.readJson(configFilePath); + async function cli() { + const options = await fs.readJson("openapi.config.json"); const swaggerSpec = await swaggerJSDoc(options); - await fs.writeJson(swaggerFilePath, swaggerSpec, { spaces: 2 }); + await fs.writeJson("openapi.json", swaggerSpec, { spaces: 2 }); } cli(); From f4892360b66ead980f879a6a79a915c251130759 Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Mon, 24 May 2021 10:45:46 +0800 Subject: [PATCH 3/4] docs(apim): remove swagger-jsdoc recommendation --- .../templates/plugins/resource/apim/README.md | 90 +------------------ 1 file changed, 3 insertions(+), 87 deletions(-) diff --git a/packages/fx-core/templates/plugins/resource/apim/README.md b/packages/fx-core/templates/plugins/resource/apim/README.md index 499ac734f3..c1cf2560bc 100644 --- a/packages/fx-core/templates/plugins/resource/apim/README.md +++ b/packages/fx-core/templates/plugins/resource/apim/README.md @@ -50,12 +50,9 @@ In the deployment step, there will be some inputs needed: > Note: This may incur costs in your Azure Subscription if you choose to create a new instance in pervious step. ## Write OpenAPI Document + We support both yaml and json format for the OpenAPI document. You need to follow the [OpenAPI Specification](https://swagger.io/resources/open-api/), author the OpenAPI document and ensure the API schema is aligned with the function implementation. -Update the Open API document under the `openapi` folder. We support both yaml and json format for the Open API document. You need to author the Open API document and ensure the API schema is aligned with the function implementation. For how to generate the Open API document, we have the following recommendations. - -### Recommended way 1: OpenAPI (Swagger) Editor in VS Code. - -Below is a sample swagger file for the default http trigger function. You can copy the content into `./openapi/openapi.json`, follow the [OpenAPI Specification](https://swagger.io/resources/open-api/), and change the content according to your modification (E.g. `/getUserProfile` -> `/$yourFunctionName` ). +Below is a sample swagger file for the default http trigger function. You can copy the content into `./openapi/openapi.json`, and change the content according to your modification (E.g. `/getUserProfile` -> `/$yourFunctionName` ). ```json { @@ -97,88 +94,7 @@ Below is a sample swagger file for the default http trigger function. You can co } } ``` - -### Recommended way 2: Using npm package swagger-jsdoc -- Annotating source code. Read [more](https://github.com/Surnet/swagger-jsdoc/) about how to use swagger-jsdoc to annotate the source code. Below is a sample annotation. - - API annotation - ```js - /** - * @openapi - * /getUserProfile: - * get: - * summary: Get User Profile - * operationId: get-user-profile - * responses: - * '200': - * $ref: "#/components/responses/getUserProfileResponse" - */ - ``` - - Response annotation - ```js - /** - * @openapi - * components: - * responses: - * getUserProfileResponse: - * description: 200 response - * content: - * application/json: - * schema: - * type: object - * properties: - * receivedHTTPRequestBody: - * type: string - * userInfoMessage: - * type: string - * graphClientMessage: - * type: object - */ - ``` -- Use swagger-jsdoc to generate OpenAPI document. Below is an example, you can learn more from [here](https://github.com/Surnet/swagger-jsdoc/tree/v7/examples/cli). - - Create an configuration `openapi/openapi.config.json` and input the title and version. Below is a sample definition file. Please change the file path `./api/getUserProfile/*` according to your modification. - ```json - { - "swaggerDefinition": { - "openapi": "3.0.1", - "info": { - "title": "{appName}", - "version": "v1" - } - }, - "apis": ["../api/getUserProfile/*"] - } - ``` - - Create `openapi/package.json` with content below. - ```json - { - "name": "swagger-jsdoc-generator", - "description": "Using swagger-jsdoc to generate OpenAPI", - "version": "0.0.1", - "type": "module", - "dependencies": { - "fs-extra": "^10.0.0", - "swagger-jsdoc": "^7.0.0-rc.6" - }, - "scripts": { - "generate": "npm install & node ./index.js" - } - } - ``` - - Create `openapi/index.js` with the content below. - ```js - import swaggerJSDoc from 'swagger-jsdoc'; - import fs from "fs-extra"; - - async function cli() { - const options = await fs.readJson("openapi.config.json"); - const swaggerSpec = await swaggerJSDoc(options); - await fs.writeJson("openapi.json", swaggerSpec, { spaces: 2 }); - } - - cli(); - ``` - - Run command `cd openapi`. - - Generate OpenAPI document `openapi/openapi.json`. Run command `npm run generate`. +You can use your favorite way to generate OpenAPI document, such as [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) and [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc/). ## Documentation From f11aa0f34b9e0592ced85af20b4cfb7e5ea1b6af Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Mon, 24 May 2021 11:59:02 +0800 Subject: [PATCH 4/4] fix(apim): fix wording according to comments --- packages/fx-core/templates/plugins/resource/apim/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/fx-core/templates/plugins/resource/apim/README.md b/packages/fx-core/templates/plugins/resource/apim/README.md index c1cf2560bc..a5f8e61c67 100644 --- a/packages/fx-core/templates/plugins/resource/apim/README.md +++ b/packages/fx-core/templates/plugins/resource/apim/README.md @@ -50,9 +50,9 @@ In the deployment step, there will be some inputs needed: > Note: This may incur costs in your Azure Subscription if you choose to create a new instance in pervious step. ## Write OpenAPI Document - We support both yaml and json format for the OpenAPI document. You need to follow the [OpenAPI Specification](https://swagger.io/resources/open-api/), author the OpenAPI document and ensure the API schema is aligned with the function implementation. + We support both yaml and json format for the OpenAPI document. You need to follow the [OpenAPI Specification](https://swagger.io/resources/open-api/), author the OpenAPI document and ensure the API schema is aligned with the Azure Functions HTTP trigger implementation. -Below is a sample swagger file for the default http trigger function. You can copy the content into `./openapi/openapi.json`, and change the content according to your modification (E.g. `/getUserProfile` -> `/$yourFunctionName` ). +Below is a sample swagger file for the default HTTP trigger function. You can copy the content into `./openapi/openapi.json`, and change the content according to your modification (E.g. `/getUserProfile` -> `/$yourFunctionName` ). ```json { @@ -94,7 +94,7 @@ Below is a sample swagger file for the default http trigger function. You can co } } ``` -You can use your favorite way to generate OpenAPI document, such as [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) and [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc/). +You can use your favorite tool to generate an OpenAPI document, such as [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) and [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc/). ## Documentation