Stack Overflow
Stack Overflow

Questions tagged [swagger]

Swagger is a framework implementation for describing, producing, consuming, and visualizing RESTful web services, based on the OpenAPI specification

Swagger is a specification and framework implementation for describing, producing, consuming and visualizing RESTful web services. It is a unique way to document your RESTful APIs on the go, as and when you code them.

The main advantage of Swagger is its flexibility - it can produce static and dynamic REST API documentation. There is even the possibility to interact with the webservice and send example queries.

It's developed by SmartBear.

On Nov 5th, 2015, the Open API Initiative extended Swagger as an OpenAPI specification to advance connected application development through open standards. Please refer to the announcement for more information.

Useful links

Frequently Asked Questions

People often ask about the following Swagger topics:

Related tags

11997 questions
44
votes
13 answers

Swagger documentation for Spring Pageable interface

I have developed a microservice using Spring Boot. The documentation for the REST API is made with Swagger. Some REST resources make use of Spring concepts to provide pagination for free. Below is an example: @RequestMapping(value = "/buckets",…
Laurent
  • 14,122
  • 13
  • 57
  • 89
44
votes
1 answer

Swagger - Specify Optional Object Property or Multiple Responses

I have an API that either returns the following response on success: { "result": "success", "filename": "my-filename.txt" } or something like below upon failure: { "result": "error", "message": "You must specify the xxx…
Programster
  • 12,242
  • 9
  • 49
  • 55
43
votes
14 answers

Swagger..Unable to render this definition The provided definition does not specify a valid version field

Unable to render this definition The provided definition does not specify a valid version field. Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for…
Paddy Popeye
  • 1,634
  • 1
  • 16
  • 29
42
votes
6 answers

How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?

I have an Asp.Net web API 5.2 project in c# and generating documentation with Swashbuckle. I have model that contain inheritance something like having an Animal property from an Animal abstract class and Dog and Cat classes that derive from…
Paolo Vigori
  • 1,612
  • 1
  • 18
  • 32
41
votes
2 answers

Re-using model with different required properties

I have a path that uses complex models with almost identical properties for each http method. The problem is that I want to define some required properties for the request of PUT and POST, while no properties are required in GET response (as the…
NotNone
  • 661
  • 1
  • 8
  • 13
41
votes
9 answers

Not supported by Swagger 2.0: Multiple operations with path

I have integrated swagger in WebApi 2 application. It works fine when application has single controller. When I added second controller in the application. I got following error : An error has occurred.","ExceptionMessage":"Not supported by…
user2266837
  • 587
  • 2
  • 5
  • 12
41
votes
3 answers

Swagger UI shows error (validation) when deployed

I have the swagger ui embedded in my application. And when I run my node application locally the UI works great. However when I deploy the UI to my 'real' server I get an error image in the bottom right of my swagger ui: I am sure this is…
lostintranslation
  • 23,756
  • 50
  • 159
  • 262
40
votes
1 answer

How to define header parameters in OpenAPI 3.0?

In OpenAPI (Swagger) 2.0, we could define header parameters like so: paths: /post: post: parameters: - in: header name: X-username But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a…
kritika agarwal
  • 505
  • 1
  • 6
  • 11
39
votes
5 answers

Get detailed error messages from AWS API Gateway Request Validator

Background I have an API Gateway created using Swagger 2.0 definitions with API Gateway extensions. I overrode the default API Gateway responses, for instance: x-amazon-apigateway-gateway-responses: BAD_REQUEST_BODY: statusCode: 400 …
Alix Axel
  • 151,645
  • 95
  • 393
  • 500
39
votes
8 answers

How to set up Swashbuckle vs Microsoft.AspNetCore.Mvc.Versioning

We have asp.net core webapi. We added Microsoft.AspNetCore.Mvc.Versioning and Swashbuckle to have swagger UI. We specified controllers as this: [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")] public class ContactController :…
Alezis
  • 2,659
  • 3
  • 27
  • 34
39
votes
5 answers

How to define global parameters in OpenAPI?

I'm preparing my API documentation by doing it per hand and not auto generated. There I have headers that should be sent to all APIs and don't know if it is possible to define parameters globally for the whole API or not? Some of these headers are…
mohamnag
  • 2,709
  • 5
  • 27
  • 40
38
votes
1 answer

Why is v2/api-docs the default URL when using springfox and Swagger2?

I'm just starting using swagger following this guide, but I found out something very weird that makes no sense for me. As far as I remember , the v2/api-docs should be used for when you have docs of the version number 2 of your API. So, the default…
jpganz18
  • 5,508
  • 17
  • 66
  • 115
38
votes
3 answers

How do you create a swagger schema that includes an array of varying types

I'm attempting to define a swagger schema definition for an object that contains an array of objects of varying types. Here is the json schema for a template object (and all related object types). I'm aware that swagger does not support the oneOf…
Mike Storey
  • 1,029
  • 3
  • 11
  • 21
37
votes
2 answers

OpenAPI 3.0 Generic Data types

How can I best describe a generic response type which includes the real data type in OpenAPI 3. Simplified example: ApiResponse: data: object error: string But the /users endpoint should give: ApiResponse> So that basically…
Jørgen
  • 2,157
  • 1
  • 23
  • 24
37
votes
3 answers

How to make Swagger show examples of objects returned from the API?

I am creating a set of API's for the first time. Here's one of the methods: // GET: api/Doors/0 /// /// Get a list of all doors for a given organization. /// /// The…
Casey Crookston
  • 13,016
  • 24
  • 107
  • 193
1 2 3
…
99 100