|
| 1 | +# M365 Spec Parser |
| 2 | + |
| 3 | +The M365 Spec Parser package is designed to parse OpenAPI specification files to generate resources for M365 applications. |
| 4 | + |
| 5 | +## Sample Usage |
| 6 | + |
| 7 | +### For NodeJS environment |
| 8 | +```typescript |
| 9 | +import { SpecParser, ParseOptions } from "@microsoft/m365-spec-parser"; |
| 10 | + |
| 11 | +// Define parsing options |
| 12 | +const option: ParseOptions = { |
| 13 | + allowMissingId: true, // Allow missing IDs in the specification, default true |
| 14 | + allowSwagger: true, // Allow Swagger specifications, default true |
| 15 | + allowAPIKeyAuth: false, // Disallow API key authentication, default false |
| 16 | + allowMultipleParameters: false, // Disallow multiple parameters, default false |
| 17 | + allowOauth2: false, // Disallow OAuth2 authentication, default false |
| 18 | +}; |
| 19 | + |
| 20 | +// Create a new SpecParser instance with the given options |
| 21 | +const parser = new SpecParser("path/to/spec/file", option); |
| 22 | + |
| 23 | +// Validate the specification |
| 24 | +const validateResult = await parser.validate(); |
| 25 | +// If the specification is not valid, log the errors and warnings |
| 26 | +if (validateResult.status !== ValidationStatus.Valid) { |
| 27 | + console.log(validateResult.errors); |
| 28 | + console.log(validateResult.warnings); |
| 29 | +} |
| 30 | + |
| 31 | +// List the operations in the specification |
| 32 | +const listResult = await parser.list(); |
| 33 | +// Log each operation |
| 34 | +for (let i = 0; i < listResult.length; i++) { |
| 35 | + console.log(listResult[i]); |
| 36 | +} |
| 37 | + |
| 38 | +// Define a filter for the operations to generate |
| 39 | +const filter = ["GET /pet/{id}"]; |
| 40 | +// Define the paths for the Teams app manifest file, the output specification file, and the output adaptive card folder |
| 41 | +const teamsAppManifestFilePath = "path/to/teamsapp/manifest/file"; |
| 42 | +const outputSpecFilePath = "path/to/output/spec/path"; |
| 43 | +const outputAdaptiveCardFolder = "adaptivecard/folder"; |
| 44 | +// Generate the operations |
| 45 | +const generateResult = await parser.generate( |
| 46 | + teamsAppManifestFilePath, |
| 47 | + filter, |
| 48 | + outputSpecFilePath, |
| 49 | + outputAdaptiveCardFolder |
| 50 | +); |
| 51 | + |
| 52 | +// If not all operations were successfully generated, log the warnings |
| 53 | +if (!generateResult.allSuccess) { |
| 54 | + console.log(generateResult.warnings); |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +### For browser environment |
| 59 | +```typescript |
| 60 | +import { SpecParser, ParseOptions } from "@microsoft/m365-spec-parser"; |
| 61 | + |
| 62 | +// Define parsing options |
| 63 | +const option: ParseOptions = { |
| 64 | + allowMissingId: false, // Allow missing IDs in the specification, default false |
| 65 | + allowSwagger: false, // Allow Swagger specifications, default false |
| 66 | + allowAPIKeyAuth: false, // Disallow API key authentication, default false |
| 67 | + allowMultipleParameters: false, // Disallow multiple parameters, default false |
| 68 | + allowOauth2: false, // Disallow OAuth2 authentication, default false |
| 69 | +}; |
| 70 | + |
| 71 | +// Create a new SpecParser instance with the given options |
| 72 | +const parser = new SpecParser("path/to/spec/file", option); |
| 73 | + |
| 74 | +// Validate the specification |
| 75 | +const validateResult = await parser.validate(); |
| 76 | +// If the specification is not valid, log the errors and warnings |
| 77 | +if (validateResult.status !== ValidationStatus.Valid) { |
| 78 | + console.log(validateResult.errors); |
| 79 | + console.log(validateResult.warnings); |
| 80 | +} |
| 81 | + |
| 82 | +// List the operations in the specification |
| 83 | +const listResult = await parser.listSupportedAPIInfo(); |
| 84 | +// Log each operation |
| 85 | +for (let i = 0; i < listResult.length; i++) { |
| 86 | + console.log(listResult[i]); |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +## Data Collection. |
| 91 | + |
| 92 | +The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. |
| 93 | + |
| 94 | +## Code of Conduct |
| 95 | + |
| 96 | +This project has adopted the [Microsoft Open Source Code of Conduct ](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 97 | + |
| 98 | +## Contributing |
| 99 | + |
| 100 | +There are many ways in which you can participate in the project, for example: |
| 101 | + |
| 102 | +- [Submit bugs and feature requests](https://github.com/OfficeDev/TeamsFx/issues), and help us verify as they are checked in |
| 103 | +- Review [source code changes](https://github.com/OfficeDev/TeamsFx/pulls) |
| 104 | + |
| 105 | +If you are interested in fixing issues and contributing directly to the code base, please see the [Contributing Guide](./CONTRIBUTING.md). |
| 106 | + |
| 107 | +## Reporting Security Issues |
| 108 | + |
| 109 | +**Please do not report security vulnerabilities through public GitHub issues.** |
| 110 | + |
| 111 | +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). |
| 112 | + |
| 113 | +If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page ](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). |
| 114 | + |
| 115 | +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). |
| 116 | + |
| 117 | +## Trademarks |
| 118 | + |
| 119 | +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies. |
| 120 | + |
| 121 | +## License |
| 122 | + |
| 123 | +Copyright (c) Microsoft Corporation. All rights reserved. |
| 124 | + |
| 125 | +Licensed under the [MIT](LICENSE.txt) license. |
0 commit comments