[NEW RELEASE] Swagger Plugin 1.1

java
plugin
sonarqube

(Zouhir OUFTOU) #1

Hi everybody,

I’am very happy to join the Sonarsource Community :slight_smile:

I have released a new SonarQube plugin to Analyzer Swagger syntax and improve API Guidelines.

Description:
This SonarQube plugin analyzes Swagger 2.0 files and:

@Sonar: Can you add this plugin to the Marketplace and the Plugin Library page, please?


(G Ann Campbell) #2

Hi,

It’s not clear to me how to test this. As far as I can tell, this plugin doesn’t declare a language. My admittedly shallow research turns up that swagger specifications can be declared in either JSON or YAML. I tried analyzing a with one of each (from here), and ended up with an empty project with one parse failure issue and nothing else.

Perhaps you could flesh out your documentation a bit?

 
Ann


(Zouhir OUFTOU) #3

I agree with you, but:
I declared a language as Swagger to avoid confusing with YAML Plugin: already developed by other people.
Just look at this class from source code.

The OpenApi Specification said that Swagger is JSON object, conform to the JSON standards.

The Swagger Plugin 1.1 analyzes this Object (not JSON format) , but the equivalent Object written in YAML.
For all files here, they are already converted from JSON format to YAML superset, witch is bad practice, i think.

From the documentation of YAML here :
“In contrast, YAML’s foremost design goals are human readability and support for serializing arbitrary native data structures.”
That why people write their REST API Description with YAML syntax.

From the link that you sent to me, in Swagger files, we find some thing like this :
application/json: |- { "instance": { "status": "ACTIVE", "updated": "2012-03-28T21:34:25Z", "name": "xml_rack_instance", "links": [ { "href": "https://openstack.example.com/v1.0/1234/instances/2450c73f-7805-4afe-a42c-4094ab42666b", "rel": "self" }, { "href": "https://openstack.example.com/instances/2450c73f-7805-4afe-a42c-4094ab42666b", "rel": "bookmark" } ],

From the (OAS) OpenAPI Specification here, you will never seen the same block with Brackets “{}” like JSON syntax.

For this reason that a Swagger Plugin return ParsingError : this syntax is not supported and doesn’t mean anything.

You can test the Plugin using this exemple from Swagger Petstore, change the content as you like to test implemented checks.

At the moment the Swagger Plugin 1.1 doesn’t support all YAML Information Models.
For the future releases, i will try to add some support for YAML supersets.

I hope that people from swagger.io will join this project to develop together some advanced functionalities.


(G Ann Campbell) #4

Hi,

There’s nothing in your documentation about the YAML plugin. Not really understanding what you were trying to convey, I decided to add YAML to my test instance, but got an error during analysis:

ERROR: Error during SonarQube Scanner execution
ERROR: Language of file 'petstore.yaml' can not be decided as the file matches patterns of both sonar.lang.patterns.swagger : **/*.yaml,**/*.yml and sonar.lang.patterns.yaml : **/*.yaml,**/*.yml

So… you should probably document the conflict with YAML. Further, you don’t follow the (yes, unstated) standard to expose a property to configure which file extensions your analyzer handles. That means that I can’t decide on a project-by-project basis which of the two analyzers I want to handle my yaml files, meaning you’ve made the two truly incompatible. At minimum, you really do need to expose file extension configuration as a property (see sonar.cs.file.suffixes under Administration > C#, sonar.css.file.suffixes under Administration > CSS, sonar.flex.file.suffixes under Administration > Flex, and so on).

I don’t understand what you’re saying. The parse error was raised on line 10, char 3, so this:

"produces": [

which is listed as part of the top-level Swagger Object. But okay, using the file you pointed to, I was able to get a full analysis.

In poking around a little bit more, I noticed that you named your rule repository “SonarQube”. Please rename it.

Also, there are a few items you might want to address with your rules:

  • I believe your parsing error rule is mis-categorized as a bug. Ours is a code smell.
  • Your file name rule has the same description as your BOM rule
  • I can’t figure out how to raise an issue with your version string rule. I set the regex to foo and got 0 issues from the rule.

 
Ann