openapitools / openapi-style-validator Goto Github PK

Hi, thank you for the maven plugin!

Why did you choose the verify phase as default?
Imho the validation phase is more appropriate, cause the vast majority of use cases is validation before compilation with the openapi-generator-maven-plugin.

Copypaste from Maven Build Lifecycle:

• validate - validate the project is correct and all necessary information is available
• compile - compile the source code of the project
• ...
• verify - run any checks on results of integration tests to ensure quality criteria are met

Using slf4j for this project is great.

But slf4j-jdk14 is a logger (java.util.logging is used as the underlying logging framework for calls made against the slf4j api).

If lib has slf4j-jdk14 as compile dependency, then nobody can use an other implementation in his project embedding the lib. He gets:

SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:file:/.../org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:file:/.../slf4j-jdk14-1.7.25.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.

Describe the bug
To reproduce:

        OpenAPI openAPI = OASFactory.createOpenAPI()
            .openapi("3.0.1")
            .info(
                OASFactory.createInfo()
                    .title("Ping Specification")
                    .version("1.0")
            )
            .addServer(
                OASFactory.createServer()
                    .url("http://localhost:8000/")
            )
            .paths(
                OASFactory.createPaths()
                    .addPathItem(
                        "/ping", OASFactory.createPathItem()
                            .GET(
                                OASFactory.createOperation()
                                    .operationId("pingGet")
                                    .responses(
                                        OASFactory.createAPIResponses()
                                            .addAPIResponse(
                                                "200", OASFactory.createAPIResponse()
                                                    .description("OK")
                                            )
                                    )
                            )
                    )
            );
        
        OpenApiSpecStyleValidator openApiSpecStyleValidator = new OpenApiSpecStyleValidator(openAPI);
        ValidatorParameters parameters = new ValidatorParameters);
        List<StyleError> validationErrors = openApiSpecStyleValidator.validate(parameters);

=> 6 errors expected in the validationErrors instance.

Stacktrace:

java.lang.NullPointerException
	at org.openapitools.openapistylevalidator.OpenApiSpecStyleValidator.validateModels(OpenApiSpecStyleValidator.java:109)
	at org.openapitools.openapistylevalidator.OpenApiSpecStyleValidator.validate(OpenApiSpecStyleValidator.java:35)

This can be fixed by adding:
.components(OASFactory.createComponents().schemas(Collections.emptyMap()))

But IMO this is not the idea.

On the classpath (maven project), to reproduce:

    <dependency>
      <groupId>org.openapitools.openapistylevalidator</groupId>
      <artifactId>openapi-style-validator-lib</artifactId>
      <version>1.1</version>
    </dependency>
    <dependency>
      <groupId>org.openapitools.empoa</groupId>
      <artifactId>empoa-simple-models-impl</artifactId>
      <version>1.0.0</version>
    </dependency>

Validation fail when for api that use the Accept-Language header with error "Accept-Language' -> parameter should be in camelCase"

I want to use camelCase for query param and path param. for header this is not possible standard headers have 'Accept-Language' or 'ACCEPT-LANGUAGE' as format.

Maybe we should add headerNamingConvention

Thanks

Describe the bug
When describing hal links (http://stateless.co/hal_specification.html) (as property), their naming convention defers from other properties:
e.g. _links, _embedded, _metadata
https://tools.ietf.org/html/draft-kelly-json-hal-08

To Reproduce
e.g.

title: Items
      type: object
      properties:
        _links:
          $ref: "#/components/schemas/LinksDefinition"

results in

*ERROR* in model Items '_embedded' -> property should be in camelCase
*ERROR* in model Items '_links' -> property should be in camelCase
*ERROR* in model Items '_metadata' -> property should be in camelCase

Expected behavior
No error raised for HAL links specific keywords (i.e._links, _embedded, _metadata) as we have no control over their naming

We need to add this to the gradle file:

plugins {
  id "org.sonarqube" version "2.8"
}

sonarqube {
  properties {
    property "sonar.projectKey", "OpenAPITools_openapi-style-validator"
    property "sonar.organization", "openapitools"
    property "sonar.host.url", "https://sonarcloud.io"
    property "sonar.login", "xxxxxxxx"
  }
}

Also, add this to the github action CI:
./gradlew sonarqube

Maybe the properties could be environment variable on the CI???

Hi, I propose to add new validation - validateModelPropertiesDescription, which will ensure that all properties of the Schemas have not empty descriptions.

Very important to stay backward compatible for a while. Maybe add a warning log when people use the old one and say it will be deleted in a future version.

Since the project was transferred from JaffSoft, it needs renaming to follow openapitools organization

You have implemented a CLI for usage. Great! - but the findings sould be available in a Sonarqube installation. I suggest to implement Sonar rules

I have found following sonar rules implementation. But this has rather less rules (9). In my opinion your rules are a great idea and sould be available via sonar!

What do you mean?

Hi, I propose to add new validation - validateModelRequiredProperties, which will ensure that all required properties of the Schemas are existing.

Success:

User:
  type: object
  required:
    - name
  properties:
    name:
      type: string

Fail:

User:
  type: object
  required:
    - id
  properties:
    name:
      type: string

Use codecov with CI + add badge

Our docusaurus version is old and complicated to update to version 2. Since we have almost nothing in the documentation, instead of going through the process of updating to version 2, I will copy the files from openapi-generator which is already on version 2 and start from here.

There are other advantage too like already a nice theme and sections that we also need.

Download the all-in-one jar (i.e. shadowJar) published on maven central:
https://repo1.maven.org/maven2/org/openapitools/openapistylevalidator/openapi-style-validator-cli/1.1/openapi-style-validator-cli-1.1-all.jar

Run it with:

java -jar openapi-style-validator-cli-1.1-all.jar 

I expect the help to be displayed but I get:

There was something wrong in your request. Please check documentation for more info

Describe the bug
When describing header parameters which do not follow any naming convention such as Accept-Version or if-none-match, I get naming convention errors for PATH and Properties

To Reproduce
e.g.

 parameters:
    acceptVersionParam:
      name: Accept-Version
      in: header

results in
*ERROR* in path GET /... 'Accept-Version' -> parameter should be in camelCase
*ERROR* in path GET / 'Accept-Version' -> parameter should be in camelCase

Expected behavior
No error raised for headers as we have no control over their naming

Is your feature request related to a problem? Please describe.
This bit of code will throw an exception (Invalid path to option files, using default.) when the path is correct but the JSON provided is invalid.

Describe the solution you'd like
Handle JSON validation. I'm happy to give this enhancement a go myself.

Describe alternatives you've considered
N/A

Additional context
N/A

This thread is to identify possible users of our project.

On the top of my head, I can identify a few:

• OpenAPI Generator who could integrate our gradle/maven plugin to validate the style of all the files used for input for the samples. That way, the project could garante that all input follow the same convention.
• All the Text Editors could possibly want to use our library natively or we could create plugins for them: https://openapi.tools/#text-editors
• Other? Please suggest ideas below.

This is an open discussion, please share any ideas. Also, if your project is using our project, please let us know!

Describe the bug
Model example validation fails on lists of items that have refs. The same case works if it is a single object property with a ref.

For example, this passes:

mapData:
          $ref: "#/components/schemas/MapData"

This fails:

airlines:
  type: array
  items:
    $ref: "#/components/schemas/Airline"

Both of those properly render valid examples in swagger.

To Reproduce
1.) Create a swagger document with a schema reference
2.) There should be at least one property that is an array of objects that uses a ref
3.) Run validation with the default settings
4.) It tells you that you are missing examples

I've attached a yaml that shows the issue. Validation on the single property passes but the array property fails, when both properly render examples in swagger.

test_examples.yaml.txt

Expected behavior
No validation errors occur if an item list renders an appropriate example in swagger.

Additional context
I attempted to do a PR but am getting a 403, however this change in OpenApiSpecStyleValidator should fix the issue:

private void validateModelProperties(String modelName, Schema model) {
        if (model.getProperties() != null) {
            model.getProperties().forEach((propertyName, property) -> {
                if (parameters.isValidateModelPropertiesExample() && property.getExample() == null
                        && ((property.getItems() == null && property.getRef() == null)
                            || (property.getItems() != null && property.getItems().getRef() == null))) {
                        errorAggregator.logMissingOrEmptyModelAttribute(modelName, propertyName, "example");
                }
            });
        }
    }

Follow the Getting Started documentation and generate the initial version
https://docusaurus.io/docs/en/installation

With OpenAPI 3.1.0 there is an new identifier to the License object.

Reference: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#licenseObject

An SPDX license expression for the API. The identifier field is mutually exclusive of the url field.

Invalid example:

openapi: 3.1.0
info:
  title: Example specification
  version: "1.0"
  license:
    name: Eclipse Public License 2.0
    url: https://www.eclipse.org/legal/epl-2.0/
    identifier: EPL-2.0
servers:
- url: http://localhost:8080/
paths:
  /ping:
    get:
      operationId: ping
      responses:
        200:
          description: OK

Hi, Maven generates warnings during parallel builds.

Log:
11:10:47,426 [BuilderThread 4] [WARNING] The following plugins are not marked @threadsafe in *some-project-name*:
11:10:47,430 [BuilderThread 4] [WARNING] org.openapitools.openapistylevalidator:openapi-style-validator-maven-plugin:1.4

As far as I figured out, the lib and the plugin are threadsafe. So, I propose to switch threadsafe value in the Mojo annotation.

Anyone with talent want to try something? Could remind of OpenAPI Generator.
Any help appreciated

The website is ugly and doesn't provide any value right now.

We need to add at least some info from the readme + real use cases, real users of the product,

This will definitely be an incremental process and this task will keep track of the progress.

Hi,
I ran the commands mentioned in readme with old github commit e8ecda5, and it runs fine.
But with new build against the latest commit ( ea18d42) the openapi-style-validator-cli-1.0.jar is not generated.

Gradle 3.5-rc-2 starts to be old.
The gradle version in this project could be updated (incl. the wrapper)

Use github actions or, if it's too complicated, Travis CI to do this.
The last time the documentation was published, it was done manually.

Describe the bug
Validator always report missing example for enum ref field

To Reproduce
Here a example Open API yaml description

openapi: 3.0.2
info:
  title: Sample API
  description: test
  version: 0.1.9
  license:
    name: test
  contact:
    name: test
paths:
  /users:
    get:
      tags:
        - users
      summary: Returns a list of users.
      operationId: listUsers
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string
components:
  schemas:
    Myobject:
      type: object
      properties:
        name:
          type: string
          example: test
        status:
          $ref: '#/components/schemas/Status'
          example: open
    Status:
      type: string
      description: |
        some description
      example: open
      enum:
        - open
        - closed

i added example field to the Status and to the Myobject > status and i still have the same error

java -jar ./cli/build/libs/openapi-style-validator-cli-1.4-SNAPSHOT-all.jar -s test.yaml 
*ERROR* in Model 'Myobject', property 'status', field 'example' -> This field should be present and not empty

Expected behavior
According to the https://editor.swagger.io/ sibling values alongside $ref are ignored
so we can't give a example for enum ref fields

@jmini and @wing328 . I will need your input on how to do this and I guess I will need some access key to be able to publish as "openapitools".

Just give me some examples and I should be able to get it running :)

Quoting @PierreBesson on twitter:

once the maven/gradle plugins are available, I would really like to see this in jhipster. Ping @cbornet

In addition to cli we could produce maven and gradle plugin that perform the validation checks and let the build fail if one rule is not respected anymore.

I have found a scenario where I have 10 paths that don't follow any rules. They are only there for legacy reasons and one day they will be deleted. I don't want to waste time on them and have validations on them.

Solution: Add an extension that will be read by the validator. The validator will totally skip this path/operation.

While I was working on #56 I have discovered that the pathNamingStrategy is not working as expected.

Test spec:

openapi: 3.0.1
info:
  title: some test
  description: some description
  version: '1.0'
  contact:
    email: "[email protected]"
  license:
    name: Apache-2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: 'http://localhost:9999/'
paths:
  /some_path/{some_id}:
    post:
      operationId: someOp
      summary: some operation
      description: some description
      parameters:
        - name: some_id
          required: true
          in: path
          schema:
            type: string
        - name: some_name
          required: true
          in: query
          schema:
            type: string
      tags:
        - some
      responses:
        '201':
          description: OK

The pathNamingStrategy should validate when set to HyphenCase and fail in the other case.

But it has no impact because of this line:

If you would like to use the lib without the cli in an other project, having the classes in org.openapitools.openapistylevalidator beeing package-protected makes it hard to use.

IMO those class should be public.

The workaround used for now is to subclass the classes like this:

package org.openapitools.openapistylevalidator;

public class ValidatorParametersEx extends ValidatorParameters {
}

and:

package org.openapitools.openapistylevalidator;

import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.openapitools.openapistylevalidator.styleerror.StyleError;

import java.util.List;

public class OpenApiSpecStyleValidatorEx extends OpenApiSpecStyleValidator{

    public OpenApiSpecStyleValidatorEx(OpenAPI openApi) {
        super(openApi);
    }
    
    @Override
    public List<StyleError> validate(ValidatorParameters parameters) {
        return super.validate(parameters);
    }
}

But I do not think that this is the idea.

I was wondering but you do not have any test for OpenApiSpecStyleValidator in the core module.

I think it would be interesting to have 1 or 2 simple cases tested.

In order to do so, you can:

• Work with: spec files + swagger-parser + empoa-swagger-core (as you do in the cli)
• Work with an other implementation of the Eclipse-MP-OpenAPI. I have written one that is implementing the interfaces as simple POJO. If you decided to go for this you will need to create the OpenAPI instance with code (which is possible).

If you are interested by the second approach, I can give you more pointers.

Originally posted by @jmini in #11 (comment)

I think they are coming from docusaurus, an update should fix everything.

Make sure to update the documentation in the readme when it's done

See what are the effect of this.

Hi there,

Just reading the instructions and I had a bit of trouble.
https://github.com/JaffSoft/swagger-style-validator#to-build

I could not get gradlew assemble to generate the mentioned jar file, and then execute the run commands.
Here are the steps I used to get it working. Perhaps the readme could be updated?

Following the Readme, no jar produced:

$ chmod +x gradlew
$ ./gradlew assemble

:modules/lib:compileJava
:modules/lib:processResources NO-SOURCE
:modules/lib:classes
:modules/lib:jar
:modules/cli:compileJava
:modules/cli:processResources NO-SOURCE
:modules/cli:classes
:modules/cli:jar
:modules/cli:assemble
:modules/lib:assemble

BUILD SUCCESSFUL

Jar produced in the following manner:

To Build

gradle build
gradle fatJar

To Run
java -jar modules/cli/build/libs/swagger-style-validator-cli-1.0.jar -s specs/petstore.yaml -o specs/options.json

From README:

Whenever an object has a property of base64 (i.e. type: string, format: byte) validation will fail the error message

*ERROR* in Model '...', property 'content', field 'example' -> This field should be present and not empty

although the field example is present. This is really tied to the property being of type base64; remove the "format: byte" and the specification document will pass validation.

To reproduce, download the attached Zip file y.zip which contains two files minimally reproducing:

• pom.xml
• broken-validation-base64-response.yaml

Run mvn verify

//exp: passes validation
//act: ERROR in Model

Describe the bug
Currently, a missing entry version in the info object does not trigger an error.

To Reproduce
Create an OpenAPI without a version in the info object. This works with API version 2.0 and 3.0.3 e.g.

{
  "swagger":"2.0",
  "info": { 
    "title":"Great API",
    "description": "A great API",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "[email protected]"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  }
}

Expected behavior
An error would indicate, that the version tag is missing.

Hi, it might be an option to add validation of data type format.
Use case:
Date time format validation.
On my current project we use custom formats (not ISO / RFC). So I'd like to have something like this in configuration:

<configuration>
    <validateDataTypeFormat>true</validateDataTypeFormat>
    <customDataTypeFormats>
        <customDataTypeFormat>my-date-time</customDataTypeFormat> 
    </customDataTypeFormats>
    <forbiddenDataTypeFormats>
        <forbiddenDataTypeFormat>date-time<forbiddenDataTypeFormat>
    </forbiddenDataTypeFormats>
</configuration>

By default all standard OAS formats are allowed and all custom formats are forbidden.

Valid schema:

User:
  type: object
  properties:
    birthDateTime:
      type: string
      format: my-date-time

Not valid schema:

User:
  type: object
  properties:
    birthDateTime:
      type: string
      format: date-time

After the merge of #35, I have the feeling that this code is not working:

I get always DEVELOPMENT with the shadow jar.

To reproduce. Run:

./gradlew build

And:

java -jar cli/build/libs/openapi-style-validator-cli-<version>.jar -v
Current version: DEVELOPMENT

Right now the core project modules/lib has a dependency on:

compile group: 'io.swagger', name: 'swagger-parser', version: '1.0.33'

This is for OpenAPI v2.

During the update to OpenAPI v3, it would be great to consider for the core module to have only a dependency on:

compile group: 'org.eclipse.microprofile.openapi', name: 'microprofile-openapi-api', version: '2.0-MR1'

This way, different parsers can be used, and the code is not coupled to swagger-parser and/or swagger-core.

The cli can still use swagger-parser to parse OpenAPI v2 and v3 specifications. To wrap a swagger-core instance into an interface of the org.eclipse.microprofile.openapi.models package, the project empoa can be used.

It seems we have a "deploy" build that keeps failing on Travis.
The "build" badge on the main page show "failing".

Here is the error:

FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':cli:publishMavenJavaPublicationToSonatypeRepository'.
> Failed to publish publication 'mavenJava' to repository 'sonatype'
   > Invalid publication 'mavenJava': multiple artifacts with the identical extension and classifier ('jar', 'null').
* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.
* Get more help at https://help.gradle.org
Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.3/userguide/command_line_interface.html#sec:command_line_warnings
BUILD FAILED in 4s
12 actionable tasks: 9 executed, 3 up-to-date
The command "./gradlew publishToSonatype -PsonatypeUser=$SONATYPE_USER -PsonatypePassword=$SONATYPE_PASSWORD" exited with 1.
Done. Your build exited with 1.

From the release notes: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components.

Replace it with a link to the official documentation that will be the "official" version of the roadmap.

Steps:

1. Create a roadmap page in the official documentation
2. Publish
3. Add a link to this in the readme.