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

2346 questions
87
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
  • 57,554
  • 29
  • 142
  • 204
73
votes
10 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
  • 2,759
  • 2
  • 17
  • 29
65
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
  • 1,427
  • 2
  • 11
  • 21
63
votes
3 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
  • 3,089
  • 2
  • 20
  • 24
60
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,524
  • 6
  • 29
  • 49
56
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: https://petstore.swagger.io/#!/pet/addPet has an enum option for the status property. How…
eloleon
  • 904
  • 2
  • 8
  • 18
46
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,121
  • 4
  • 23
  • 44
45
votes
1 answer

What is Swagger and does it relate to OData?

I am familiar with the Microsoft stack. I am using OData for some of my restful services. Recently I came across Swagger for API documentation and I am trying to understand how it relates to OData. Both of them seem to be RESTful specifications.…
Muthukumar
  • 6,437
  • 14
  • 52
  • 78
44
votes
2 answers

How to describe this POST JSON request body in OpenAPI (Swagger)?

I have a POST request that uses the following JSON request body. How can I describe this request body using OpenAPI (Swagger)? { "testapi":{ "testapiContext":{ "messageId":"kkkk8", "messageDateTime":"2014-08-17T14:07:30+0530" …
Anirban Sen Chowdhary
  • 7,918
  • 4
  • 34
  • 76
42
votes
1 answer

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
  • 8,205
  • 5
  • 38
  • 61
40
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
  • 21,036
  • 19
  • 98
  • 176
40
votes
3 answers

Swagger Editor shows the "Schema error: should NOT have additional properties" error for a path parameter

I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address: Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0] should NOT have additional properties additionalProperty: type,…
Emanuel Ey
  • 2,288
  • 4
  • 26
  • 37
37
votes
4 answers

How to define mutually exclusive query parameters in Swagger (OpenAPI)?

I have a series of parameters in Swagger like this "parameters": [ { "name": "username", "description": "Fetch username by username/email", …
lorless
  • 3,138
  • 8
  • 26
  • 39
32
votes
2 answers

Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Although I have seen the examples in the OpenAPI spec: type: object additionalProperties: $ref: '#/definitions/ComplexModel' it isn't obvious to me why the use of additionalProperties is the correct schema for a Map/Dictionary. It also doesn't…
Chen Levy
  • 12,926
  • 16
  • 67
  • 86
32
votes
2 answers

Swagger: map of

I need to document with Swagger an API that uses, both as input and output, maps of objects, indexed by string keys. Example: { "a_property": { "foo": { "property_1": "a string 1", "property_2": "a string 2" …
Xavier Lamorlette
  • 704
  • 1
  • 8
  • 16
1
2 3
…
99 100