Extension proposal #1638
Merged
Extension proposal #1638
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
veronicagg
reviewed
Dec 7, 2016
| ## Objectives and High-level plan | ||
|
|
||
| We plan on building a one-stop shop vs-code extension that will help the swagger authors get live and prompt feedback on the quality and correctness of their swaggers. We plan on reusing and building on top of the work that was done for the Autorest Linter VS code extension and integration our tools Autorest to simplify the users experience. | ||
|
|
There was a problem hiding this comment.
It may be useful to describe the scenarios (and priorities) we're aiming to solve (or simplify), so if we want to consider other options we can evaluate them based on these; and what may be non-goals for these tools. For example: provide swagger authors validation when creating a new swagger spec from scratch, assist with editing/updating of a swagger spec, ability to run the back-end tools as part of CI, assist with swagger spec reviews, etc.
| 1. SVT VS Code extension's client: the client is the implementation of UI and experience of the swagger authoring, details will follow later in the document on the proposed user experience. The swagger tooling team will take ownership of this component. | ||
|
|
||
| 2. SVT VS Code server component: The Autorest team will be owning this component and the current plan is to: | ||
|
|
There was a problem hiding this comment.
We may want to add some of the considerations we mentioned offline, like the ability for AutoRest to run on any platform, the fact that the current extension is triggered by 'any' json file load (not just swagger file).
|
|
||
| ### Swagger Validation tools types | ||
|
|
||
| Our classification of the tools will be based on how expense the tool is to run and whether all the information required for the validation is contained within the swagger itself or not. |
There was a problem hiding this comment.
'expense' -> 'expensive'
| - The user creates a new swagger or edits an existing one in VS code. | ||
| - As the user updates the document no requests will be sent to Autorest to fire up long running validation tools. | ||
| - When the user is ready to run a specific long running validation tools he will trigger it by: | ||
| - Selecting the JOSON file or giving it focus in VS Code. |
There was a problem hiding this comment.
Hey, it's Samer's doc... I wasn't proofreading it 🌝
|
|
||
| - The user opens VS code and creates a new Swagger or edits an existing one. | ||
| - As he';s typing, in the background the SVT extension's client will be calling the extension's server (which is basically Autorest) and uploading the updated swagger content. | ||
| - The swagger server will trigger the configured and registered tools for "only the fly validation" and return the standardized messages If applicable. |
|
|
||
| >  | ||
|
|
||
| Figure (4) trigger long running operations through the file explorer's context menu |
There was a problem hiding this comment.
If we also want to cover "making it easier to review swagger specs" in this document, we may want to add a section for that and include some thoughts on that. It'd be nice to have some process to "check-out" and review a spec in PR, as well as to add comments that end up published in GitHub.
There was a problem hiding this comment.
@amarzavery and I chatted quickly today about reviewing-- if we want to make a github code review extension, I'm all for that, but since there's no reason that they need to be 1 extension, we should probably make two if that's the case. (since, the PR feedback and swagger stuff will work perfectly independently anyway).
| 3. Pluggable linter rules: the Autorest team will be working on a design and interface to allow anyone to contribute static linting rules in a more scalable (not directly authored into the code) way. The swagger volition tools team or anyone from the services team will be able to contribute to the rules as they see fit. | ||
|
|
||
| 4. Pluggable Validation tools: The swagger tooling team will mainly be responsible for building these tools except for the linter which will continue to be owned by the Autorest team, but that wouldn't stop contribution from anyone else. in the efforts of simplifying the user experience and potentially simplifying the process of integrating our tools with any IDE in the future (such as Visual Studio), all the validation tools will be hooked up to extension points on Autorest which is currently work in progress on Autorests side. Our tools can all be run through simple commands but we're committed to update them to adhere with any integration requirements from Auto-rest. | ||
|
|
There was a problem hiding this comment.
For swagger authors, we may also want to provide some type of navigation facility, to view/peek #definitions, or refer to defined ones (with intellisense), autocompletion, etc, to improve the creating/editing experience.
|
Anyone know Samer's github id? |
|
@salameer - you can directly edit and push changes to this branch too if you want to update stuff. |
fearthecowboy
pushed a commit
that referenced
this pull request
Feb 3, 2017
* Ref resolving improvements (#1708) * composite external resolving revised * preprocessor (header resolving) * tmp YAML merging override to unblock arm-recoveryservicesbackup (#1713) [NOTE] - Admin merging because TravisCI has dishonored itself and should be shamed. * tmp composite swagger merge override to unblock arm-recoveryservicesbackup * skip test * Added code to change the data type of ItemType (#1711) * Extension proposal (#1638) [Admin merging - docs ] * fixed typo in autorest.json files * Fixed linefeeds, better c# simplifier * regenerated python (line endings) * regenerated ruby (line endings) * regenerated nodejs (line endings) * regenerated c# (line endings) * regenerated samples (line endings) * merged from master and regenerated * whitelist assemblies that should be signed * imported draft document * [Ruby] Making credentials nil by default (#1677) * Making credentials nil by default * Regenerated Samples * [Linter Rules] M1005, M1006, M1007 & M1009 (#1706) * Implement OperationNameValidation Rule for M1005, M1006, M1007 & M1009 * Update warning message * Adding swagger modeler validation tests * Correcting the clean swagger and improving the rules correctness * [linter Rules] Swagger rules M2005 - long running operation must have valid terminal status codes (#1707) * Long running operations must have valid success response codes. * Adding swagger modeler validation tests for invalid long running reponse codes * Adding nullable check on response codes before schema resolver * Adding positive test case for correctly modeled x-ms-long-running * Correct the merge conflicted resx file syntax * Add insights swagger spec test, add vm extensions to swagger and schema (#1512) * Add ServiceBus AzureResourceSchema acceptance test * Add insights swagger spec test * Add minLength and maxLength support to schema generator * Fixing logic to add missing schema resources * Working on discriminator stuff * Change schemas that only have an 'object' type definition to be empty * Add compute test with extension properties * Add additional enum values for extensionType discriminator * missing test files * Update SwaggerSpecHelper.cs unnecessary file change * Update SwaggerSpecHelper.cs unnecessary file change * [Linter Rules] M2008 for x-ms-mutability extension (#1712) * x-ms-mutability swagger linter rules * Removing <<<< characters * undo unblocking fix (#1718) * Improvements for Mono & Docker users (#1714) * Make Docker shell script executable * Remove unnecessary dependencies * Update documentation for AutoRest Mono/Docker usage * Better preprocessor and 3 bugfixes (#1717) * general $inc handling * more preproc magic * move up path params and do cleanup * fixed Stream.Null codegen * enum default escaping * added operationId and title as optional properties of the example schema (#1725) * Fix NullReferenceException (#1722) See #1721 for problem and solution. * minor code cleanup in swagger validation rule file (#1724) * Generator should not flatten out parameters if they are polymorphic (#1726) * Changes to markdown file generation in AzureResourceSchema generator. (#1715) The doc team requested the following changes so they can start consuming the generated markdown help files. - generate a separate file for each resource type - use namespace/type instead of just namespace - include optional properties in the template sample - move type into its own column - remove line-breaks from tables - re-word some of the boiler-plate text - don't bold text when listing a type's values * Relaxing naming rules to accomodate suffix words in names * [Go] Telemetry tiny detail (#1731) * Fix for credentials switch (#1728) * Fix for list and dict serialization (#1727) * [Java] AutoRest changes by runtime changes (#1703) * Fix some tests with beta5 snapshot runtime * Runtime change: mapperAdapter to serializerAdapter * Runtime change: CollectionFormat moved * Runtime changes: Use RestClient for generic clients * Fix paging test * Get rid of gradle and use maven * Use pluggable response builder * Finish up response builder factory * [Azure/autorest-clientruntime-for-java#119] rename ServiceCall#create() * [fixes Azure/autorest-clientruntime-for-java#125] remove all references to old callback classes * Revert to previous next method annotation * Support fragmented paging * [#1426] Tests for fragment paging * Update scripts and docs to use maven * Support custom logging interceptor * Remove composite swagger modeler fix * Remove android footprint * Reduce complexity on exception construction * Consistent naming for getters and setters * Remove duplicate RestClient imports * Fix maven test runner in gulpfile * Fix Enum name generation * Add JsonProperty everywhere * Regenerate samples * Fixed AutoRest.Python.Azure.Tests.AcceptanceTests.SampleTestForGeneratingPython (#1759) * Update AcceptanceTests.cs * Update SwaggerSpecHelper.cs * Remove Azure extensions configuration from __init__ in Python (#1745) * Remove nextLink check in Python * Remove Azure extensions from __init__ in Python * Regenerate Python tests * [Azure.Python] Update setup.py dependency on msrestazure * [Azure.Python] Regenerate Azure Python tests * Xml support (#1744) * Swagger schema adjustment * wip -1 * removed old xml gen * xml model * tests * real path * additional test * test server * wip 5 * xml wip * missing files * fixes * Tweaked enum serialization * generic deserialization * isWrapped serialization support * rfc date * niklas * new properties * fix response header creation * refactor and remove custom (de)serialization * naming * unnecessary whitespace change * fixed templates to be non-xml sensitive * regen * regen * fixed nullable dictionary xml deserialization and regened petstoreV2 * cleanup * xml serialization fix * fixed testcase * another special case for list serialization * Literate File Formats (#1743) * Drafting Literate docs * test data format * updated doc * more * literate Swagger * added literate-metadata * added literate-metadata * updated docs * Got rid of ReadOnly validation (#1749) * Fixed and improved UniqueResourcePaths linter rule (#1768) * fixed UniqueResourcePaths * addressed feedback * cleaner code gen (less unnecessary code) (#1771) * Make S.X.X a build-time dependency. * Fix #1738 (#1772) * cleaner code gen (less unnecessary code) * add disambiguation * fixed test * regex valitation for dictionary values (#1773) * Code changes to generate resources/subresources (#1769) Code changes to generate resources/subresources in ruby based on the standard definitions defined in MSRestAzure * Removing sanitization for redable output paths * Eliminate // in the Path output * Update SwaggerModelerCompareTests * Fix generation of ARM markdown help files. (#1765) Include API specific name property instead of the generic one (it provides better doc text than the generic "name of the resource" one). Merge AllOf/Properties into a flat list so that AllOf is included. Removed EnsureUniqueFileName as it's not needed. Fix unnecessary nesting output directories. Fixed a silly bug in InlineLink missing a '#' character. * Adding new property for readable log output * Linter Validation rules (#1751) * Adding Validation Rule to check the format for API Version * Fix the regular expression * Added validation to check the HTTP Verb * Added validation to check the properties of resources and their read only preoperties * Added validation is resource validation must have x-ms-azure-resource extension * Fixed the condition * Added Validation to check if the delete operation have empty body * Added validation to validate x-ms-client-name field * Fix the signature * Added validation to check the response of put/get/patch operations * Fixed the signature * Added validation to discourage usage of Guid * Added code to validate if operations API has been implemented * Added code to validate tracked resources * Added code to validate properties of tracked resources * Additional changes * Fix the Build Issue * Response to PR comments * Added Test cases * Added more test cases * Fixing test cases * Removed circular dependency test case * adjusted master's changes & used new razor tool
fearthecowboy
pushed a commit
that referenced
this pull request
Feb 10, 2017
* Ref resolving improvements (#1708) * composite external resolving revised * preprocessor (header resolving) * tmp YAML merging override to unblock arm-recoveryservicesbackup (#1713) [NOTE] - Admin merging because TravisCI has dishonored itself and should be shamed. * tmp composite swagger merge override to unblock arm-recoveryservicesbackup * skip test * Added code to change the data type of ItemType (#1711) * Extension proposal (#1638) [Admin merging - docs ] * fixed typo in autorest.json files * Fixed linefeeds, better c# simplifier * regenerated python (line endings) * regenerated ruby (line endings) * regenerated nodejs (line endings) * regenerated c# (line endings) * regenerated samples (line endings) * merged from master and regenerated * whitelist assemblies that should be signed * imported draft document * [Ruby] Making credentials nil by default (#1677) * Making credentials nil by default * Regenerated Samples * [Linter Rules] M1005, M1006, M1007 & M1009 (#1706) * Implement OperationNameValidation Rule for M1005, M1006, M1007 & M1009 * Update warning message * Adding swagger modeler validation tests * Correcting the clean swagger and improving the rules correctness * [linter Rules] Swagger rules M2005 - long running operation must have valid terminal status codes (#1707) * Long running operations must have valid success response codes. * Adding swagger modeler validation tests for invalid long running reponse codes * Adding nullable check on response codes before schema resolver * Adding positive test case for correctly modeled x-ms-long-running * Correct the merge conflicted resx file syntax * Add insights swagger spec test, add vm extensions to swagger and schema (#1512) * Add ServiceBus AzureResourceSchema acceptance test * Add insights swagger spec test * Add minLength and maxLength support to schema generator * Fixing logic to add missing schema resources * Working on discriminator stuff * Change schemas that only have an 'object' type definition to be empty * Add compute test with extension properties * Add additional enum values for extensionType discriminator * missing test files * Update SwaggerSpecHelper.cs unnecessary file change * Update SwaggerSpecHelper.cs unnecessary file change * [Linter Rules] M2008 for x-ms-mutability extension (#1712) * x-ms-mutability swagger linter rules * Removing <<<< characters * undo unblocking fix (#1718) * Improvements for Mono & Docker users (#1714) * Make Docker shell script executable * Remove unnecessary dependencies * Update documentation for AutoRest Mono/Docker usage * Better preprocessor and 3 bugfixes (#1717) * general $inc handling * more preproc magic * move up path params and do cleanup * fixed Stream.Null codegen * enum default escaping * added operationId and title as optional properties of the example schema (#1725) * Fix NullReferenceException (#1722) See #1721 for problem and solution. * minor code cleanup in swagger validation rule file (#1724) * Generator should not flatten out parameters if they are polymorphic (#1726) * Changes to markdown file generation in AzureResourceSchema generator. (#1715) The doc team requested the following changes so they can start consuming the generated markdown help files. - generate a separate file for each resource type - use namespace/type instead of just namespace - include optional properties in the template sample - move type into its own column - remove line-breaks from tables - re-word some of the boiler-plate text - don't bold text when listing a type's values * Relaxing naming rules to accomodate suffix words in names * [Go] Telemetry tiny detail (#1731) * Fix for credentials switch (#1728) * Fix for list and dict serialization (#1727) * [Java] AutoRest changes by runtime changes (#1703) * Fix some tests with beta5 snapshot runtime * Runtime change: mapperAdapter to serializerAdapter * Runtime change: CollectionFormat moved * Runtime changes: Use RestClient for generic clients * Fix paging test * Get rid of gradle and use maven * Use pluggable response builder * Finish up response builder factory * [Azure/autorest-clientruntime-for-java#119] rename ServiceCall#create() * [fixes Azure/autorest-clientruntime-for-java#125] remove all references to old callback classes * Revert to previous next method annotation * Support fragmented paging * [#1426] Tests for fragment paging * Update scripts and docs to use maven * Support custom logging interceptor * Remove composite swagger modeler fix * Remove android footprint * Reduce complexity on exception construction * Consistent naming for getters and setters * Remove duplicate RestClient imports * Fix maven test runner in gulpfile * Fix Enum name generation * Add JsonProperty everywhere * Regenerate samples * Fixed AutoRest.Python.Azure.Tests.AcceptanceTests.SampleTestForGeneratingPython (#1759) * Update AcceptanceTests.cs * Update SwaggerSpecHelper.cs * Remove Azure extensions configuration from __init__ in Python (#1745) * Remove nextLink check in Python * Remove Azure extensions from __init__ in Python * Regenerate Python tests * [Azure.Python] Update setup.py dependency on msrestazure * [Azure.Python] Regenerate Azure Python tests * Xml support (#1744) * Swagger schema adjustment * wip -1 * removed old xml gen * xml model * tests * real path * additional test * test server * wip 5 * xml wip * missing files * fixes * Tweaked enum serialization * generic deserialization * isWrapped serialization support * rfc date * niklas * new properties * fix response header creation * refactor and remove custom (de)serialization * naming * unnecessary whitespace change * fixed templates to be non-xml sensitive * regen * regen * fixed nullable dictionary xml deserialization and regened petstoreV2 * cleanup * xml serialization fix * fixed testcase * another special case for list serialization * Literate File Formats (#1743) * Drafting Literate docs * test data format * updated doc * more * literate Swagger * added literate-metadata * added literate-metadata * updated docs * Got rid of ReadOnly validation (#1749) * Fixed and improved UniqueResourcePaths linter rule (#1768) * fixed UniqueResourcePaths * addressed feedback * cleaner code gen (less unnecessary code) (#1771) * Make S.X.X a build-time dependency. * Fix #1738 (#1772) * cleaner code gen (less unnecessary code) * add disambiguation * fixed test * regex valitation for dictionary values (#1773) * Code changes to generate resources/subresources (#1769) Code changes to generate resources/subresources in ruby based on the standard definitions defined in MSRestAzure * Removing sanitization for redable output paths * Eliminate // in the Path output * Update SwaggerModelerCompareTests * Fix generation of ARM markdown help files. (#1765) Include API specific name property instead of the generic one (it provides better doc text than the generic "name of the resource" one). Merge AllOf/Properties into a flat list so that AllOf is included. Removed EnsureUniqueFileName as it's not needed. Fix unnecessary nesting output directories. Fixed a silly bug in InlineLink missing a '#' character. * Adding new property for readable log output * Linter Validation rules (#1751) * Adding Validation Rule to check the format for API Version * Fix the regular expression * Added validation to check the HTTP Verb * Added validation to check the properties of resources and their read only preoperties * Added validation is resource validation must have x-ms-azure-resource extension * Fixed the condition * Added Validation to check if the delete operation have empty body * Added validation to validate x-ms-client-name field * Fix the signature * Added validation to check the response of put/get/patch operations * Fixed the signature * Added validation to discourage usage of Guid * Added code to validate if operations API has been implemented * Added code to validate tracked resources * Added code to validate properties of tracked resources * Additional changes * Fix the Build Issue * Response to PR comments * Added Test cases * Added more test cases * Fixing test cases * Removed circular dependency test case * Cache version strings after first generation. (#1784) * Cache version strings after first generation. Also, rewrite CodeNamerGo method to be more readable and have fewer allocations. * Responding to PR comments. * Adding missing package imports to template. * Reversing change that made two fields static. * Update readme to reflect requirements of repo build (#1719) * Update ms_rest and ms_rest_azure version for tests * Update minimum required runtime version message * Fix bug in parameter grouping in some languages (#1775) - The bug was that parameter group "transform" has to happen after the groups are processed. In CSharpAzure and CSharpFluent, it was happening too early and so the language specific capitalization rules wern't being applied. * Fix ruby rspec test to deserialize post long-running operation * fix cross referencing models in relative swagger specs (#1805) * Fixed constant parameter (#1796) * Make Python tests less nervous about Exception string content (#1781) * [Go] Added x-ms-parametrized-host support (#1803) * wip * fix dat razor * [Go] Adding support fo x-ms-parametrized-host * Fixed bug 1763 and added unit tests (#1800) * Fixed bug 1763 and added unit tests * Fixed failing test * Fixed comments * Checking files for proper ctor text * Addressed comment * Fixing format bug preventing Go gen. (#1795) * [Linter] Adding rule to warn about boolean type properties (#1783) * Adding rule to warn about boolean type properties * Adding test case for rule * [ReadMe] Change commands to fixed width font (#1774) * Hotfix after Java runtime beta5 release * java tests * regen * merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.