Stack Overflow
Stack Overflow

Questions tagged [openapi]

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful Web services.

A variety of tools can generate code, documentation and test cases given an interface file. Development of the OpenAPI Specification (OAS) is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Ref: https://en.wikipedia.org/wiki/OpenAPI_Specification

Related tags

4284 questions
170
votes
7 answers

How can I represent 'Authorization: Bearer ' in a Swagger Spec (swagger.json)

I am trying to convey that the authentication/security scheme requires setting a header as follows: Authorization: Bearer This is what I have based on the swagger documentation: securityDefinitions: APIKey: type: apiKey name:…
Elmer Thomas
  • 2,068
  • 2
  • 13
  • 11
161
votes
1 answer

How to define a property that can be string or null in OpenAPI (Swagger)?

I have JSON schema file where one of the properties is defined as either string or null: "type":["string", "null"] When converted to YAML (for use with OpenAPI/Swagger), it becomes: type: - 'null' - string but the Swagger Editor shows an…
Vaibhav Patil
  • 2,603
  • 4
  • 14
  • 22
139
votes
5 answers

What is the correct way to declare a date in an OpenAPI / Swagger-file?

What is the correct way to declare a date in a swagger-file object? I would think it is: startDate: type: string description: Start date example: "2017-01-01" format: date But I see a lot of declarations like these: startDate: …
Patrick Savalle
  • 4,068
  • 3
  • 22
  • 24
111
votes
13 answers

Swagger/OpenAPI mock server

I have an API reference in a Swagger file. I want to create a very simple mock server, so that when I call e.g.: mymockurl.com/users it will return a predefined JSON (no need to connect to a database). What's the easiest way to do this? I'm not a…
rafakob
  • 3,946
  • 3
  • 26
  • 36
111
votes
3 answers

How can I generate swagger based off of existing postman collection?

I am developing a REST API. during development I have used postman (chrome extension) to use and document my API. It is a wonderful tool and I have most of my API endpoints in it. However, as we near release I would like to document this API in…
StuBob
  • 1,490
  • 2
  • 10
  • 13
99
votes
3 answers

How to define UUID property in JSON Schema and Open API (OAS)

When using JSON Schema and Open API specification (OAS) to document a REST API, how do I define the UUID property?
Slava Fomin II
  • 26,865
  • 29
  • 124
  • 202
99
votes
2 answers

Swagger/OpenAPI - use $ref to pass a reusable defined parameter

Let's say I've got a parameter like limit. This one gets used all over the place and it's a pain to have to change it everywhere if I need to update it: parameters: - name: limit in: query description: Limits the number of returned…
brandonscript
  • 68,675
  • 32
  • 163
  • 220
96
votes
3 answers

How to specify if a field is optional or required in OpenAPI/Swagger?

How to I define in OpenAPI/Swagger if a field is optional or required and what is the default?
user79074
  • 4,937
  • 5
  • 29
  • 57
80
votes
2 answers

How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?

I have the following schema definition: swagger: '2.0' ... definitions: Service: type: object properties: serviceId: type: string description: Device or service identification number example: 1111111111 …
saeedj
  • 2,179
  • 9
  • 25
  • 38
80
votes
4 answers

How to define an enum in OpenAPI (Swagger)?

Does anyone know how to define possible enum values in an OpenAPI 2.0 definition so that they will be displayed in the Model tab of Swagger UI? Example here has an enum option for the status property. How to do define such an enum in OpenAPI 2.0?
eloleon
  • 1,144
  • 2
  • 10
  • 18
78
votes
2 answers

Swagger; specify two responses with same code based on optional parameter

This question is not a duplicate of (Swagger - Specify Optional Object Property or Multiple Responses) because that OP was trying to return a 200 or a 400. I have a GET with an optional parameter; e.g., GET /endpoint?selector=foo. I want to return…
Tommy
  • 12,588
  • 14
  • 59
  • 110
77
votes
7 answers

How to describe a model in Swagger for an array with simple objects?

I have a REST services to document, some of them accepts simple array like: [ { "name":"a" }, { "name":"b" }, { "name":"c" } ] How do I describe this in Swagger model section ? I can only create 'named array' like model { properties: { "arr":…
razor
  • 2,727
  • 6
  • 33
  • 45
76
votes
4 answers

How to post files in Swagger (OpenAPI)?

I am using Swagger to document my REST services. One of my services requires a CSV file to be uploaded. I added the following to the parameters section in my JSON API definition: { "name": "File", "description": "The file in zip…
CodeGuru
  • 2,722
  • 6
  • 36
  • 52
74
votes
3 answers

Convert OpenAPI 3.0 to Swagger 2.0

Is there a generator to convert OpenAPI 3.0 to Swagger 2.0? Mashery, an API gateway, requires Swagger 2.0 format on input to open endpoint.
Michal Foksa
  • 11,225
  • 9
  • 50
  • 68
69
votes
6 answers

How to define an optional parameter in path using swagger

There is a function in my REST web service working with GET method and it has two optional parameters. I tried to define it in Swagger but I encountered an error, Not a valid parameter definition, after I set the required as false. I found out that…
Hedeshy
  • 1,266
  • 2
  • 15
  • 24
1
2 3
…
99 100