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

[CADL API view] Improve CADL instructions for upload #5273

Closed
Tracked by #5761
catalinaperalta opened this issue Jan 30, 2023 · 3 comments
Closed
Tracked by #5761

[CADL API view] Improve CADL instructions for upload #5273

catalinaperalta opened this issue Jan 30, 2023 · 3 comments
Assignees
Labels
APIView Central-EngSys This issue is owned by the Engineering System team. TypeSpec Issues or feature requests for tooling to support TypeSpec (Cadl)

Comments

@catalinaperalta
Copy link
Member

While working with a service partner recently it became clear that the instructions for uploading an APIView for CADL should be improved.

Suggested instructions:

  1. Install @azure-tools/cadl-apiview
  2. Compile and emit the apiview file: cadl compile .\main.cadl --emit "@azure-tools/cadl-apiview"
  3. Upload the JSON file that is emitted.
@ghost ghost added the needs-triage Workflow: This is a new issue that needs to be triaged to the appropriate team. label Jan 30, 2023
@catalinaperalta
Copy link
Member Author

@catalinaperalta catalinaperalta added APIView TypeSpec Issues or feature requests for tooling to support TypeSpec (Cadl) labels Jan 30, 2023
@catalinaperalta
Copy link
Member Author

Another improvement could be to make it more obvious that a CADL or JSON file is accepted. It would be good if the whole screen didn't go to an error when the JSON API view token file is uploaded or the space is left empty. A more descriptive error could help in understanding what the problem is.

Same thing happened when adding a revision, it was not immediately obvious that the dropdown should be used to be able to upload the CADL token file as a JSON. When the dropdown is set to Cadl there is no button to upload a file since it is expecting a URL and it is not intuitive to change the dropdown option from Cadl since the API view is for a Cadl spec.

image

image

In this case we decided to simply not choose a language to get the instructions or to upload since that seemed to be the problem. Initially we were unable to add a revision as well.

@maririos maririos removed the needs-triage Workflow: This is a new issue that needs to be triaged to the appropriate team. label Jan 31, 2023
@maririos maririos added the Central-EngSys This issue is owned by the Engineering System team. label Jan 31, 2023
@github-project-automation github-project-automation bot moved this to 🆕 New in ApiView Jan 31, 2023
@maririos maririos moved this from 🤔Triage to 📋Backlog in Azure SDK EngSys 🚢🎉 Jan 31, 2023
@azure-sdk azure-sdk removed this from ApiView Jan 31, 2023
@github-project-automation github-project-automation bot moved this to 🆕 New in ApiView Jan 31, 2023
@catalinaperalta
Copy link
Member Author

catalinaperalta commented Feb 1, 2023

Instructions as to what URL to use in the API view instructions section would also be appreciated. If the CADL is in PR, should it be a link to the main.cadl file in that PR?

@praveenkuttappan praveenkuttappan moved this from 📋 Backlog to ✅ Done in ApiView Mar 27, 2023
@praveenkuttappan praveenkuttappan moved this from ✅ Done to 🏗 In progress in ApiView Mar 29, 2023
@praveenkuttappan praveenkuttappan moved this from 📋Backlog to 🔬Dev in PR in Azure SDK EngSys 🚢🎉 Apr 3, 2023
@praveenkuttappan praveenkuttappan moved this from 🏗 In progress to ✅ Done in ApiView Apr 3, 2023
@github-project-automation github-project-automation bot moved this from 🔬Dev in PR to 🎊Closed in Azure SDK EngSys 🚢🎉 Apr 3, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
APIView Central-EngSys This issue is owned by the Engineering System team. TypeSpec Issues or feature requests for tooling to support TypeSpec (Cadl)
Projects
Status: ✅ Done
Development

No branches or pull requests

6 participants