en-US/about_tcs.openapi.help.txt
|
TOPIC about_tcs.openapi SHORT DESCRIPTION Generates PowerShell modules from OpenAPI 3.0/3.1 and Swagger 2.0 documents, and provides the request engine those modules use. LONG DESCRIPTION tcs.openapi has two halves. The generator (Import-OpenApiDocument, Test-OpenApiDocument and New-OpenApiModule) reads a document, normalises it to one OpenAPI 3-shaped model, reports problems as findings and writes a module with one thin wrapper command per operation. The runtime (Set-, Get-, Remove-OpenApiContext and Invoke-OpenApiRequest) is the engine every generated module calls: authentication, parameter serialisation, request bodies, retry, paging, errors and downloads. Generated modules list tcs.openapi in RequiredModules, so updating tcs.openapi fixes every generated module without regenerating it. Both halves run on Windows PowerShell 5.1 and PowerShell 7 (Windows, Linux and macOS). tcs.openapi requires tcs.core 0.4.1. QUICK START Check the document, generate a module, import it and call it: Test-OpenApiDocument -Path ./petstore.json | Where-Object Severity -NE 'Information' # No findings: nothing is returned and 'No problems found in # petstore.json (<n> operations).' is shown. -Summary returns counts. New-OpenApiModule -Path ./petstore.json -ModuleName PetStore ` -NounPrefix PetStore -OutputPath ./out Import-Module ./out/PetStore/PetStore.psd1 Set-PetStoreContext -ApiKey (Read-Host -AsSecureString -Prompt 'Key') Get-PetStorePet -Status available -All Always set -NounPrefix. There is no default prefix, so without one the command nouns come straight from the operationIds and easily clash with other modules. A name that would shadow a core PowerShell command (Get-Item, New-Item, ...) gets the PascalCase module name as its prefix instead, with finding OA042. For APIs that wrap every result in an envelope such as { "data": ..., "traceId": ... }, pass -UnwrapProperty data: the commands then return the value of 'data' (when a response has it) instead of the whole response. -Raw always returns the whole response. THE GENERATED MODULE <OutputPath>/<ModuleName>/ <ModuleName>.psd1 manifest; RequiredModules tcs.openapi <ModuleName>.psm1 loads the metadata, the commands, then Overrides.ps1 OpenApi/operations.json operation metadata used by the engine OpenApi/source.json the normalised document Public/<Tag>/<Verb>-<Noun>.ps1 one command per operation Public/_Connection/ Set-, Get- and Remove-<Prefix>Context Overrides.ps1 yours: never overwritten README.md the list of commands en-US/about_<ModuleName>.help.txt the module's about topic Regenerate with -Force to replace generated files. Overrides.ps1 is created once and never replaced: a function defined there replaces the generated command of the same name. CONNECTIONS AND AUTHENTICATION Set-<Prefix>Context (or Set-OpenApiContext -Service <ModuleName>) stores the base URI and credentials for the session. -BaseUri defaults to the first absolute http(s) server of the document. apiKey (header, query or cookie) -ApiKey <SecureString> http basic -Credential <PSCredential> http bearer -BearerToken <SecureString> oauth2 clientCredentials -ClientId -ClientSecret [-TokenUri] [-Scope] oauth2 / openIdConnect with a token you already have -BearerToken The engine uses the first security requirement of the operation (or of the document) whose schemes all have credentials in the context. security: [] sends no credentials. OAuth2 tokens are cached until 60 seconds before they expire and fetched again once after a 401. -Persist saves the settings as JSON and the secrets with tcs.core Set-ModuleSecret; a later session loads them on first use. Get-<Prefix>Context shows every secret as ********. PAGING, DOWNLOADS AND RAW RESPONSES Pageable operations get -All, which streams the items as they arrive. Without -All one page is returned. Either way the output is the items, typed with the item schema name ('<Service>.<Schema>'). Three kinds are detected: nextLink x-ms-pageable, or a nextLink/next/@odata.nextLink property next to one array: the link is followed (same host only, never twice) token a nextToken/pageToken/cursor/continuationToken query parameter and a response with one array and a nextToken/nextPageToken/next_cursor (or same-named) property: the request is repeated with the token until it is empty or repeats linkHeader a Link response header with rel="next" Operations with a binary response get -OutFile, which streams the body to a file and returns the FileInfo. Without -OutFile the bytes are returned as one byte[]. -Raw returns { StatusCode, Headers, Content } instead of objects. PATH PARAMETERS Values are escaped as one path segment ('a/b' is sent as a%2Fb). A router-style catch-all segment at the end of a path ('/files/*path', or '{path*}') is read as the path parameter of that name, flagged CatchAll: its value keeps its slashes and each segment is escaped on its own (leading and trailing slashes are dropped). allowReserved path parameters are sent the same way. Test-OpenApiDocument reports a path parameter that is not in the path (OA023) and a {placeholder} without a path parameter (OA024). ERRORS, RETRY AND LOGGING A non-2xx response is a non-terminating error with the id OpenApi.<Service>.<StatusCode>; transport failures use OpenApi.<Service>.Connection. TargetObject holds the method, URI, status, headers, the parsed (problem+json) body and the operationId. -ErrorAction and pipelines behave as for any cmdlet. 408, 429, 500, 502, 503 and 504 are retried for idempotent methods, 429 and 503 only for POST and PATCH, honouring Retry-After (MaxRetries in the context, default 3). -Verbose shows each request line and status; -Debug adds headers and bodies with Authorization, cookies, api keys and properties named like password, secret or token replaced by ********. NAMING x-ps-name (a full Verb-Noun) wins, then x-ps-verb and x-ps-noun. Otherwise the verb comes from the first word of the operationId (get/list -> Get, create/add -> New, update -> Set or Update, delete -> Remove, ...) or from the HTTP method, and the rest is the noun: <NounPrefix> plus the PascalCase words, with the last word singular. A last word that repeats the operation's HTTP method is dropped (ConnectorGet -> Get-Connector, ConnectorPost -> New-Connector). Collisions add a path segment or the method (OA040); parameters that clash with common parameters get a location suffix (OA041). HELP AND DOCUMENTATION SITES The help of the generated commands is plain text that PlatyPS can turn into Markdown for MDX sites (Docusaurus, Astro Starlight) and plain Markdown sites: HTML and Markdown from the document are converted, words with '<', '{' or '}' and the operation ids and paths are code spans, and every example has a description. New-OpenApiModule -HelpUri 'https://docs.example.com/api/{0}' makes each command's page its online help ({0} is the command name). The manifest gets ProjectUri and LicenseUri from the document. WHATIF AND CONFIRM A generated command has -WhatIf and -Confirm when it can change data: every DELETE (ConfirmImpact High); every POST, PUT and PATCH (ConfirmImpact Medium) except Get- and Test- commands, because an operationId that starts with get, list, find, search, query, validate, check or verify is a read that some APIs send as a POST with a body; and any command whose verb changes state (New, Set, Remove, Start, Stop, Restart, Reset, Update). Other GET, HEAD and OPTIONS commands have neither, so a read still runs under $WhatIfPreference = $true. SEE ALSO Import-OpenApiDocument Test-OpenApiDocument New-OpenApiModule Set-OpenApiContext Invoke-OpenApiRequest https://github.com/ntatschner/TheCodeSaiyan-PowerShell-tcs.openapi |