swagger

How to define enum mapping in OpenAPI?

by

OpenAPI 3.1 OpenAPI 3.1 uses the latest JSON Schema, and the recommended way to annotate individual enum values in JSON Schema is to use oneOf+const instead of enum. This way you can specify both custom names (title) and descriptions for enum values. Severity: type: integer oneOf: – title: HIGH const: 2 description: An urgent problem … Read more

Swagger: Add description with ref

by

For anyone using Swashbuckle with ASP.NET, you can use the following code to have the $ref construct put under the allOf (just like the : // do this wherever you are calling AddSwaggerGen() ArgBuilder.Services.AddSwaggerGen(opts => { opts.UseAllOfToExtendReferenceSchemas(); // add this line. }); Now if you have a model with two properties of the same type, … Read more

How can I describe complex json model in swagger

by

Okay, so based on the comments above, you want the following schema: { “definitions”: { “user”: { “type”: “object”, “required”: [ “name” ], “properties”: { “name”: { “type”: “string” }, “address”: { “type”: “array”, “items”: { “$ref”: “#/definitions/address” } } } }, “address”: { “type”: “object”, “properties”: { “type”: { “type”: “string”, “enum”: [ “home”, … Read more

Swashbuckle parameter descriptions

by

With the latest Swashbuckle, or better said at least the Swashbuckle.AspNetCore variant which I’m using, the Description field for parameters can now be displayed correctly as output. It does require the following conditions to be met: XML comments must be enabled and configured with Swagger Parameters should be explicitly decorated with either [FromRoute], [FromQuery], [FromBody] … Read more

How to generate java client code for swagger REST API documentation

by

Instead of using the JAR, you can also use https://generator.swagger.io to generate the SDKs (Java, Ruby, PHP, etc) online without installing anything. Here is an example: curl -X POST -H “content-type:application/json” -d ‘{“swaggerUrl”:”http://petstore.swagger.io/v2/swagger.json”}’ https://generator.swagger.io/api/gen/clients/java and here is a sample response: {“code”:”1445940806041″,”link”:”https://generator.swagger.io/api/gen/download/1445940806041″} You can then download the zipped SDK from the link. For more options on … Read more

Swagger UI passing authentication token to API call in header

by

@ApiImplicitParams and @ApiImplicitParam should do the trick: @GET @Produces(“application/json”) @ApiImplicitParams({ @ApiImplicitParam(name = “Authorization”, value = “Authorization token”, required = true, dataType = “string”, paramType = “header”) }) public String getUser(@PathParam(“username”) String userName) { … } From the documentation: You may wish you describe operation parameters manually. This can be for various reasons, for example: Using … Read more