Would it be possible to add support for the @BeanParam (https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/BeanParam.html) from JAX-RS? Same question as answered at http://stackoverflow.com/questions/19913046/does-swagger-support-the-jax-rs-beanparam-annotation, but didn't find an issue for it here.

When I first noticed this bug I thought it happens only when I use ApiParam and ApiImplicitParams at the same time.

Looks like ApiImplicitParams is ignored in any case. As result I can't document security token which intercepted by servlet filter earlier.

Here is endpoint

@GET
@Consumes("text/plain")
@Produces(MediaType.APPLICATION_JSON)
@Path("testParams")
@ApiOperation(response = String.class, value = "Returns string with provided parameter")
@ApiImplicitParams({@ApiImplicitParam(name = "token", required = true, dataType = "string", paramType = "query", value = "API token")})
public String testParams(@ApiParam(required = false, value = "ID of timesheet") @QueryParam("id") int id) {}

Example project is located at https://github.com/cppexpert/broken_swagger_jaxrs_integration

Hi

I have successfully configured Swagger with our Jax-rs/Jersey 2 application. Works fine with maven jetty plugin and on Tomcat test server

However, when deploying to Websphere 7, no resources are listed. The /api-docs resources returns

{"apiVersion":"1.0","swaggerVersion":"1.2"}

My BeanConfig looks like this

 BeanConfig beanConfig = new BeanConfig();
 beanConfig.setVersion(apiVersion);
 beanConfig.setResourcePackage(resourcePackage);
 beanConfig.setBasePath(basePath);
 beanConfig.setDescription("EK resources");
 beanConfig.setTitle("EK API");
 beanConfig.setScan(true);

(apiVersion, resourcePackage and basePath are defined in a properties file and injected by Spring)

Not sure how to get past this. We would like to have our APIs documented when running in our production and qa environments

Dependency in pom.xml

<groupId>com.wordnik</groupId>
<artifactId>swagger-jersey2-jaxrs_2.10</artifactId>
<version>1.3.12</version>

By default array or List of integers is generated in UI with example:

"eventTypes": [0],

I've tried to add "example" property, but that:

@ApiModelProperty(required = true, example = "[2, 3]")
private int[] lorem;

generates example values as string:

"eventTypes": "[2, 3]",

Other options like "2, 3" don't work neither. In result to have valid json in example it has to have only one value, zero.

To replicate this issue, use a data model similar to this one:

https://gist.github.com/TomDataworks/56e2b6e259fd1b971aa8

The XmlAccessType.NONE configuration requires explicit declaration of all JAXB Elements, and behaves as expected when using a JacksonJaxbJsonProvider in Apache CXF. However, when exposing the API listing via Swagger, the definitions match exactly what the JacksonJsonProvider or a standard ObjectMapper would produce.

The element marked @XmlElement(name="body") does not appear in the definition of Message. While @XmlAccessorType(XmlAccessType.NONE) is specified, any elements that are explicitly defined should appear.

There are a number of ObjectMappers in the Swagger codebase, and I am trying to track down which one is responsible for this particular task (generating the definitions).

I have a very straightforward use-case, following the Swagger JAX-RS example and anything I could find in 48 hours of Googling.

Here's the embedded Grizzly2 server:

URI baseUri = UriBuilder.fromUri("http://0.0.0.0/").port(port).build();
ResourceConfig masterApplication = new MasterApplication(); // This extends PackagesResourceConfig
webServer = GrizzlyServerFactory.createHttpServer(baseUri, masterApplication);

Here's the Swagger ApiListing:

import com.wordnik.swagger.jersey.listing.ApiListing;

@Path("/resources.json")
@Api("/resources")
@Produces(MediaType.APPLICATION_JSON)
public class MyriaApiListing extends ApiListing {
}

And here's the missing dependency error:

Jun 20, 2013 3:09:54 PM com.sun.jersey.spi.inject.Errors processErrorMessages
SEVERE: The following errors and warnings have been detected with resource and/or provider classes:
  SEVERE: Missing dependency for method public javax.ws.rs.core.Response com.wordnik.swagger.jersey.listing.ApiListing.apiListing(java.lang.String,javax.ws.rs.core.Application,com.sun.jersey.spi.container.servlet.WebConfig,javax.ws.rs.core.HttpHeaders,javax.ws.rs.core.UriInfo) at parameter at index 2
  SEVERE: Method, public javax.ws.rs.core.Response com.wordnik.swagger.jersey.listing.ApiListing.apiListing(java.lang.String,javax.ws.rs.core.Application,com.sun.jersey.spi.container.servlet.WebConfig,javax.ws.rs.core.HttpHeaders,javax.ws.rs.core.UriInfo), annotated with GET of resource, class com.wordnik.swagger.jersey.listing.ApiListing, is not recognized as valid resource method.
  SEVERE: Missing dependency for method public javax.ws.rs.core.Response com.wordnik.swagger.jersey.listing.ApiListing.resourceListing(javax.ws.rs.core.Application,com.sun.jersey.spi.container.servlet.WebConfig,javax.ws.rs.core.HttpHeaders,javax.ws.rs.core.UriInfo) at parameter at index 1
  SEVERE: Method, public javax.ws.rs.core.Response com.wordnik.swagger.jersey.listing.ApiListing.resourceListing(javax.ws.rs.core.Application,com.sun.jersey.spi.container.servlet.WebConfig,javax.ws.rs.core.HttpHeaders,javax.ws.rs.core.UriInfo), annotated with GET of resource, class com.wordnik.swagger.jersey.listing.ApiListing, is not recognized as valid resource method.
Exception in thread "main" com.sun.jersey.spi.inject.Errors$ErrorMessagesException
    at com.sun.jersey.spi.inject.Errors.processErrorMessages(Errors.java:170)
    at com.sun.jersey.spi.inject.Errors.postProcess(Errors.java:136)
    at com.sun.jersey.spi.inject.Errors.processWithErrors(Errors.java:199)
    at com.sun.jersey.server.impl.application.WebApplicationImpl.initiate(WebApplicationImpl.java:770)
    at com.sun.jersey.api.container.ContainerFactory.createContainer(ContainerFactory.java:172)
    at com.sun.jersey.api.container.ContainerFactory.createContainer(ContainerFactory.java:134)
    at com.sun.jersey.api.container.grizzly2.GrizzlyServerFactory.createHttpServer(GrizzlyServerFactory.java:242)
    at edu.washington.escience.myriad.api.MasterApiServer.<init>(MasterApiServer.java:43)
    at edu.washington.escience.myriad.daemon.MasterDaemon.<init>(MasterDaemon.java:48)
    at edu.washington.escience.myriad.daemon.MasterDaemon.main(MasterDaemon.java:30)

I've tried this with swagger-jaxrs and swagger-jersey-jaxrs, and that just makes the error message flip between ServletConfig and WebConfig.

Various issues on GitHub (#146, #136, #64) appear to reference this problem or problems like it, and seem to be merged with the code base, but I still have the issue.

Any advice?

Thanks! Dan

Hey guys,

Please take a look on this enhancement which allows to use multiple Swagger configurations per single servlet (more precisely, ServletConfig). Essentially, this is more generic approach than the one taken by https://github.com/swagger-api/swagger-core/issues/1482 and is using the base path as a unique context discriminator. The original discussion has been started here https://groups.google.com/forum/#!topic/swagger-swaggersocket/bf7uVBWYRTw and the solution suggested by @frantuma has been implemented.

There are two configuration parameters available:

• Servlet init parameter 'swagger.use.path.based.config' = true | false
• usePathBasedConfig property of BeanConfig

When those properties are set, the SwaggerContextService is going to use base path to uniquely identify the API Swagger's configuration components: context, config and scanner. This is very important in multiple use cases, for example when many independent APIs are deployed using single servlet (the best exampe could be OSGi container).

This approach works quite well for deploying multiple Swagger configs in the same JVM and even within same servlet. As the further suggestion, we could simplify SwaggerContextService a lot by removing SCANNER_ID_KEY, CONTEXT_ID_KEY and CONFIG_ID_KEY and rely solely on path-based configuration (less boilerplate to the users with the same goals being achieved).

What do you think guys? Thanks a lot.

PS: The original issue was posted to Apache CXF JIRA is https://issues.apache.org/jira/browse/CXF-6740

Best Regards, Andriy Redko & Aki Yoshida

Hi, Swagger is not able to map Mongo ObjectId correctly. My model class looks something like this:

public class Person implements Serializable { @org.jongo.marshall.jackson.oid.Id @ObjectId private String id; // internal mongo db id ...

Swagger gives me response something like this:

  "_id": {
    "date": 1343026573000,
    "time": 1343026573000,
    "timestamp": 1343026573,
    "new": false,
    "timeSecond": 1343026573,
    "inc": 402653369,
    "machine": 808430687
  }

Instead I expect something like this: "_id": "406b5b3de4b8dde5f3000000"

I have seen already existing issues and tried following things but nothing seems to work.

1. Using @ApiModelProperty(dataType= "string") annotation of my id field but it's not working.
2. I tried using Overriding model in my bootstrap servlet but no help.

import com.wordnik.swagger.converter.*;

String jsonString = "{" + " "_id" : "ObjectId" "+ "}"; OverrideConverter converter = new OverrideConverter(); converter.add(ObjectId.class.getName(), jsonString); ModelConverters.addConverter(converter, true);

But it's not working, may be I'm doing it wrong way.

1. I also tried using Typeconverter but didn't solve the issue:

     ```
     TypeConverter typeConverter = new TypeConverter();
     typeConverter.add("_id", "string");
     ModelConverters.addConverter(typeConverter, true);
     ```
   

Anyone who has faced the same issue and able to find any work around for this, please revert.

Thanks

on ui it shows the queryparam datatype as CsvIntegerParameter instead of string. By overriding the model with converter, it doesn't seem to help in case of query param for deserialization.

If I compare to the joda datetime, it seems to be able to show it as "string". Any idea how I can achieve similarly for a custom datatype object for a query param.

I'm looking for a way where I can this below type: to be "string"

{
name: "testInts",
description: "test ints",
required: false,
type: "CsvIntegerParameter",
paramType: "query",
allowMultiple: false
},

from my bean param:

@ApiModelProperty(value = "test ints", dataType = "string")
    @ApiParam(value = "test ints")
    @QueryParam("testInts")
    @JsonProperty("testInts")
    private CsvIntegerParameter testInts;

In post body of Model schema, it shows correctly as expected

Here's how I had done override String jsonString = "{" + " "id": "CsvIntegerParameter"," + " "properties": {" + " "values": {" + " "required": false," + " "description": "comma separated ints"," + " "notes": "Add any notes you like here"," + " "type": "string"," + " "format": "int32"" + " }" + " }" + "}"; OverrideConverter converter = new OverrideConverter(); converter.add("reporting.model.CsvIntegerParameter", jsonString);

The reflection can't find proper generic model property.

public class ResultList<T> {
    private List<T> results;
    public List<T> getResults() {
        return results;
    }
    public void setResults(List<T> results) {
        this.results = results;
    }
}
class UserResultList extends ResultList<User> {
}

The reflection can find the ResultList results property, but it shows as an array of objects. To work around, I have to override the methods:

class OfferResultList extends ResultList<Offer> {
    @Override
    public List<Offer> getResults() {
        return super.getResults();
    }
    @Override
    public void setResults(List<Offer> results) {
        super.setResults(results);
    }
}

The issue also exists in the method return types. I looked at the code and seems it's not trivial to make a fix. All reflection functions are expecting a Class[_] rather than Type.

Using the swagger-scala module, need to migrate play support into a new module. This is probably best done in a new artifact, and outside of swagger-core.

After replaced the option required at @Schema annotation by requiredMode on #4286, it seems the issue #3438 is shown again.

According to the comments of ArraySchema annotation, ArraySchema.schema defines the model of the items within the array, while ArraySchema.arraySchema defines the model for the model of the array itself.

Example

In this example, I provide an almost same example at the #3438.

For the below DTO class:

public class Person {
    @ArraySchema(
        arraySchema = @Schema(requiredMode = RequiredMode.REQUIRED)
    )
    private List<String> addresses;
}

I expect the generated special to have (but it's not):

{
  "Person": {
    "required": [
      "addresses"
    ]
  }
}

And I need to work around this by:

public class Person {
    @ArraySchema(
        arraySchema = @Schema(description = "The person"),
        schema = @Schema(requiredMode = RequiredMode.REQUIRED)
    )
    private List<String> addresses;
}

With the changes to @Schema to deprecate the required attribute and replace it with requiredMode in #4286 the auto resolution accounts for annotations directly on the attribute. A nice enhancement would be to also consider any meta-annotations as well. For example:

I have the following custom annotation

@Constraint(validatedBy = {})
@NotNull(message = "must be a valid verification code")
@Pattern(regexp = VERIFICATION_CODE_REGEX, message = "must be a valid verification code")
public @interface ValidVerificationCode {
...
}

It would be nice to have this auto resolved as not null as well by the Schema.RequiredMode.AUTO.

Expected Behavior

According to the OpenAPI specification I should be able to write an OpenAPI document that contains null values.

See for reference: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#data-types https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaNullable

Current Behavior

If I write the OpenAPI document completely by hand (programmatically or the text document itself) it works without any problems but when I use POJO classes that contains fields annotated with @Schema e.g.: @Schema(nullable = true, example = "null") it doesn’t always work correctly.

After serialization in the OpenAPI document some fields don’t have an example value at all, and others have converted null values. For the following types from a "null" value it produces:

• integer, number
  • No example
• string
  • "null" string value
• boolean
  • False
• object, array:
  • null, It works as expected

I’ve noticed that regardless of the "nullable" property only the object and array types work correctly.

Possible Solution

Annotation processing should respect the "nullable" property and if that is true and the example is "null”, and the field has no constraints: it should produce in the OpenAPI document an example with a null value regardless of the annotated data type.

Steps to Reproduce

1. Mark a field with any data type (excluding object, array) with @Schema(nullable = true, example = "null").
2. After serialization in the OpenAPI document it should produce incorrect or missing example fields.

I’ve created an example web project to test this: https://github.com/bodzso/swagger-nullable-test

Context (Environment)

I’m trying to generate an OpenAPI document from POJOs and endpoints. Currently I cannot produce working requests that works with swagger-ui because of the errors described above. As far as I know it isn’t possible to disable default value generation in swagger-ui and with the above errors combined I didn’t find a possible workaround. Writing the entire OpenAPI document by hand isn’t feasible because the generated one is over a thousand lines.

I’d like to achieve a simple thing: don’t send some optional (nullable) fields in certain examples and don't hide (@Schema(hidden = true)) these fields from the Schema.

For some reason, I'm using swagger-parser to parse Json to OpenAPI object. However, the json-string is pretty large (about 1MB), it takes about half a minute to analyze it every time, so I want to cache the OpenAPI object in some way. But the OpenAPI class itself does not implement serializable, so I can't do in in native way. Is there any tool for me to realise this?

Hi

While using Springdoc project, I've noticed it's not possible to document the data structure of an endpoint returning a List<List<Integer>>.

This limitation is due to the fact that @ArraySchema annotation is missing the ability to nest.

Would it be possible to add this feature in the upcoming version ?

See my original issue on springdoc github repository.

Hi! I want to use example with another pattern in DateTimeSchema. Now DateTimeSchema extends Schema and I can't override example. There are two ways to solve this problem. 1. Change OffsetDateTime on String but I think this can break the behavior which users expect. 2. Change method «clone» in ModelResolver. Replace Json.mapper() on _mapper. This does not break the behavior which users expect and I can only write custom ObjectMapper to change DateTimeSchema extends from StringSchema. I did pull request with branch name clone-by-outer-mapper.