Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release typespec-apiview #5615

Merged
merged 3 commits into from
Mar 7, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions tools/apiview/emitters/cadl-apiview/.eslintrc.cjs

This file was deleted.

8 changes: 0 additions & 8 deletions tools/apiview/emitters/cadl-apiview/.prettierrc.yaml

This file was deleted.

6 changes: 6 additions & 0 deletions tools/apiview/emitters/typespec-apiview/.eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
require("@typespec/eslint-config-typespec/patch/modern-module-resolution");

module.exports = {
extends: "@typespec/eslint-config-typespec",
parserOptions: { tsconfigRootDir: __dirname },
};
8 changes: 8 additions & 0 deletions tools/apiview/emitters/typespec-apiview/.prettierrc.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
trailingComma: "all"
printWidth: 120
quoteProps: "consistent"
endOfLine: lf
arrowParens: always
plugins:
- "./node_modules/@typespec/prettier-plugin-typespec"
overrides: [{ "files": "*.tsp", "options": { "parser": "typespec" } }]
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Release History

## Version 0.3.5 (Unreleased)
## Version 0.4.0 (03-06-2023)
Update for rename of Cadl to TypeSpec.

## Version 0.3.5 (02-10-2023)
Support latest release of Cadl compiler.
**BREAKING CHANGE**: Removed the `--namespace` emitter option.
Added the `--service` emitter option to support filtering output for multi-service specs.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# Cadl APIView Emitter
# TypeSpec APIView Emitter

This package provides the [Cadl](https://github.com/microsoft/cadl) emitter to produce APIView token file output from Cadl source.
This package provides the [TypeSpec](https://github.com/microsoft/typespec) emitter to produce APIView token file output from TypeSpec source.

## Install

Add `@azure-tools/cadl-apiview` to your `package.json` and run `npm install`.
Add `@azure-tools/typespec-apiview` to your `package.json` and run `npm install`.

## Emit APIView spec

1. Via the command line

```bash
cadl compile {path to cadl project} --emit=@azure-tools/cadl-apiview
tsc compile {path to typespec project} --emit=@azure-tools/typespec-apiview
```

2. Via the config

Add the following to the `cadl-project.yaml` file.
Add the following to the `typespec-project.yaml` file.

```yaml
emitters:
@azure-tools/cadl-apiview: true
@azure-tools/typespec-apiview: true
```

For configuration [see options](#emitter-options)
Expand All @@ -29,53 +29,53 @@ For configuration [see options](#emitter-options)

1. Log in to the API View site (apiview.dev)[https://apiview.dev].
2. Click the blue "Create Review" button in the bottom-right corner of the screen.
3. In the first block, load the token file generated by the `cadl-apiview` emitter.
3. In the first block, load the token file generated by the `typespec-apiview` emitter.

## Revise API View

1. Log in to the API View site (apiview.dev)[https://apiview.dev].
2. Navigate to your review.
3. Click the "Revisions" tab in the top left.
4. Click the blue "Add Revision" button in the bottom-right corner of the screen.
5. In the first block, load the token file generated by the `cadl-apiview` emitter.
5. In the first block, load the token file generated by the `typespec-apiview` emitter.

## Use APIView-specific decorators:

Currently there are no APIView-specific decorators...

## Emitter options:

Emitter options can be configured via the `cadl-project.yaml` configuration:
Emitter options can be configured via the `tspconfig.yaml` configuration:

```yaml
emitters:
'@azure-tools/cadl-apiview':
'@azure-tools/typespec-apiview':
<optionName>: <value>


# For example
emitters:
'@azure-tools/cadl-apiview':
'@azure-tools/typespec-apiview':
output-file: my-custom-apiview.json
```

or via the command line with

```bash
--option "@azure-tools/cadl-apiview.<optionName>=<value>"
--option "@azure-tools/typespec-apiview.<optionName>=<value>"

# For example
--option "@azure-tools/cadl-apiview.output-file=my-custom-apiview.json"
--option "@azure-tools/typespec-apiview.output-file=my-custom-apiview.json"
```

### `emitter-output-dir`

Configure the name of the output directory. Default is `cadl-output/@azure-tools/cadl-apiview`.
Configure the name of the output directory. Default is `tsc-output/@azure-tools/typespec-apiview`.

### `include-global-namespace`

Normally, APIView will filter all namespaces and only output those in the service namespace and any
subnamespaces. This is to filter out types that come from the Cadl compiler and supporting libraries.
subnamespaces. This is to filter out types that come from the TypeSpec compiler and supporting libraries.
This setting, if `true`, tells APIView to output the contents of the global (empty) namespace, which
would normally be excluded.

Expand All @@ -93,13 +93,13 @@ all services in a multi-service spec, the output filename will be the service ro

### `version`

For multi-versioned Cadl specs, this parameter is used to control which version to emit. This
is not required for single-version specs. For multi-versioned specs, the unprojected Cadl will
For multi-versioned TypeSpec, this parameter is used to control which version to emit. This
is not required for single-version specs. For multi-versioned specs, the unprojected TypeSpec will
be rendered if this is not supplied. For multi-service specs, this option cannot be supplied
unless the `service` option is also set.

## See also

- [Cadl Getting Started](https://github.com/microsoft/cadl#getting-started)
- [Cadl Tutorial](https://github.com/microsoft/cadl/blob/main/docs/tutorial.md)
- [Cadl for the OpenAPI Developer](https://github.com/microsoft/cadl/blob/main/docs/cadl-for-openapi-dev.md)
- [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
- [TypeSpec Tutorial](https://github.com/microsoft/typespec/blob/main/docs/tutorial.md)
- [TypeSpec for the OpenAPI Developer](https://github.com/microsoft/typespec/blob/main/docs/typespec-for-openapi-dev.md)
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ trigger:
- hotfix/*
paths:
include:
- tools/apiview/emitters/cadl-apiview
- tools/apiview/emitters/typespec-apiview

pr:
branches:
Expand All @@ -19,11 +19,11 @@ pr:
- hotfix/*
paths:
include:
- tools/apiview/emitters/cadl-apiview
- tools/apiview/emitters/typespec-apiview

variables:
NodeVersion: '16.x'
CadlEmitterDirectory: 'tools/apiview/emitters/cadl-apiview'
TypeSpecEmitterDirectory: 'tools/apiview/emitters/typespec-apiview'
ArtifactName: 'apiview'
FeedRegistry: 'https://registry.npmjs.org/'

Expand All @@ -44,23 +44,23 @@ stages:

- script: |
npm install
workingDirectory: $(CadlEmitterDirectory)
displayName: "Install npm packages for CADL emiter"
workingDirectory: $(TypeSpecEmitterDirectory)
displayName: "Install npm packages for TypeSpec emiter"

- script: |
npm run-script build
workingDirectory: $(CadlEmitterDirectory)
displayName: "Build CADL emitter"
workingDirectory: $(TypeSpecEmitterDirectory)
displayName: "Build TypeSpec emitter"

- script: |
npm run-script test
workingDirectory: $(CadlEmitterDirectory)
displayName: "Test CADL emitter"
workingDirectory: $(TypeSpecEmitterDirectory)
displayName: "Test TypeSpec emitter"

- pwsh: |
npm pack $(CadlEmitterDirectory)
npm pack $(TypeSpecEmitterDirectory)
Copy-Item ./*.tgz $(Build.ArtifactStagingDirectory)
displayName: "Pack CADL Emitter"
displayName: "Pack TypeSpec Emitter"

- task: PublishBuildArtifacts@1
inputs:
Expand All @@ -73,7 +73,7 @@ stages:
condition: Succeeded()
jobs:
- job: PublishPackage
displayName: 'Publish cadl-apiview package to devops feed'
displayName: 'Publish typespec-apiview package to devops feed'
pool:
name: azsdk-pool-mms-ubuntu-2204-general
vmImage: MMSUbuntu22.04
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ words:
- azurecr
- blockful
- blockless
- cadl
- typespec
- Contoso
- CRUDL
- devdriven
Expand Down Expand Up @@ -62,6 +62,6 @@ ignorePaths:
- "**/node_modules/**"
- "**/dist/**"
- "**/dist-dev/**"
- "**/cadl-output/**"
- "**/tsp-output/**"
enableFiletypes:
- cadl
- tsp
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"name": "@azure-tools/cadl-apiview",
"version": "0.3.5",
"name": "@azure-tools/typespec-apiview",
"version": "0.4.0",
"author": "Microsoft Corporation",
"description": "Cadl library for emitting APIView token files from Cadl specifications",
"description": "Library for emitting APIView token files from TypeSpec",
"homepage": "https://github.com/Azure/azure-sdk-tools",
"readme": "https://github.com/Azure/azure-sdk-tools/blob/master/README.md",
"license": "MIT",
Expand All @@ -14,7 +14,7 @@
"url": "https://github.com/Azure/azure-sdk-tools/issues"
},
"keywords": [
"cadl",
"typespec",
"apiview"
],
"type": "module",
Expand All @@ -33,39 +33,38 @@
]
}
},
"cadlMain": "dist/src/index.js",
"typespecMain": "dist/src/index.js",
"engines": {
"node": ">=16.0.0"
},
"scripts": {
"clean": "rimraf ./dist ./temp",
"prebuild": "node -p \"'export const LIB_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'\" > src/version.ts",
"build": "npm run prebuild && tsc -p . && npm run lint-cadl-library",
"build": "npm run prebuild && tsc -p . && npm run lint-typespec-library",
"watch": "tsc -p . --watch",
"lint-cadl-library": "cadl compile . --warn-as-error --import @cadl-lang/library-linter --no-emit",
"lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
"test": "mocha",
"test-official": "c8 mocha --forbid-only --reporter mocha-multi-reporters",
"lint": "eslint . --ext .ts --max-warnings=0",
"lint:fix": "eslint . --fix --ext .ts"
},
"files": [
"lib/*.cadl",
"lib/*.tsp",
"dist/**",
"!dist/test/**"
],
"dependencies": {
"@azure-tools/cadl-azure-core": "0.26.0",
"@azure-tools/cadl-autorest": "0.26.0",
"@azure-tools/cadl-dpg": "latest",
"@cadl-lang/compiler": "0.40.0",
"@cadl-lang/rest": "latest",
"@cadl-lang/versioning": "latest"
"@azure-tools/typespec-azure-core": "0.27.0",
"@azure-tools/typespec-autorest": "0.27.0",
"@typespec/compiler": "0.41.0",
"@typespec/rest": "0.41.0",
"@typespec/versioning": "0.41.0"
},
"devDependencies": {
"@cadl-lang/eslint-plugin": "~0.40.0",
"@cadl-lang/library-linter": "~0.40.0",
"@cadl-lang/prettier-plugin-cadl": "^0.40.0",
"@cadl-lang/eslint-config-cadl": "~0.4.1",
"@typespec/eslint-plugin": "~0.41.0",
"@typespec/library-linter": "~0.41.0",
"@typespec/prettier-plugin-typespec": "^0.41.0",
"@typespec/eslint-config-typespec": "~0.6.0",
"@types/mocha": "~9.1.0",
"@types/node": "~16.0.3",
"@changesets/cli": "^2.24.4",
Expand Down
Loading