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
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

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
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
1 answer

How to refer to enclosing type definition recursively in OpenAPI / Swagger?

I'm writing an OpenAPI definition in Swagger Editor. One of my type definitions contains an array containing child elements of the same type as the parent. I.e. something like this: definitions: TreeNode: type: object properties: …
Morten
  • 684
  • 1
  • 5
  • 15
36
votes
6 answers

How do I combine multiple OpenAPI 3 specification files together?

I want to combine an API specification written using the OpenAPI 3 spec, that is currently divided into multiple files that reference each other using $ref. How can I do that?
heitortsergent
  • 1,971
  • 2
  • 20
  • 23
36
votes
1 answer

OpenAPI 3.0 - how to define file download operation correctly

I use online Swagger Editor with OpenAPI 3.0 and I have to create a definition file download. I develop server-side and a customer should be able to create a client using YAML description without my "addition explanation". The relevant part of YAML…
bw_dev
  • 775
  • 1
  • 7
  • 17
36
votes
3 answers

Swagger complex response model with dynamic key value hash maps

I'm struggling with the syntax of swagger to describe a response type. What I'm trying to model is a hash map with dynamic keys and values. This is needed to allow a localization. The languages may vary, but english should always be provided. The…
user1736217
  • 425
  • 1
  • 4
  • 7
33
votes
5 answers

Use java.time.Instant to represent DateTime instead of OffsetDateTime

I'm using the openApi maven plugin to generate java request/responses for a REST api. The request has a DateTime property, when I run the generator I get the DateTime property of the attribute represented as java.time.OffsetDateTime. The problem is…
sromdhane
  • 375
  • 1
  • 4
  • 7
32
votes
1 answer

Swagger schema properties ignored when using $ref - why?

I'm trying to build a Swagger model for a time interval, using a simple string to store the time (I know that there is also datetime): definitions: Time: type: string description: Time in 24 hour format "hh:mm". TimeInterval: type:…
mvc
  • 653
  • 1
  • 5
  • 9
31
votes
2 answers

How to generate OpenAPI 3.0 YAML file from existing Spring REST API?

I have an existing Spring REST API for which I want to generate the OpenAPI 3.0 YAML file and not Swagger 2.0 JSON/YAML? Since as of now, SpringFox does not support YAML generation. It generates JSON with Swagger 2.0 (which follows OPEN API 3.0…
Dev Utkarsh
  • 1,377
  • 2
  • 18
  • 43
30
votes
3 answers

How to generate OpenAPI 3 documentation from protobuf files

I have an API generated from protobuf, and I would like to generate documentation conforming to the OpenAPI 3 spec. I've looked at a number of utilities but I haven't found a combination that works. Does anyone know of a path from protobuf to…
KHilse
  • 301
  • 1
  • 3
  • 4
29
votes
2 answers

Open API vs. REST API - difference

How is Open API different from a REST API exposed on Internet? When Open API is explained it explains about an API getting exposed in LAN against exposing it to public . So what exactly is the difference?
Harish Narayanan
  • 554
  • 1
  • 5
  • 8
29
votes
1 answer

Post a json body with swagger

I would like to POST a json body with Swagger, like this : curl -H "Content-Type: application/json" -X POST -d {"username":"foobar","password":"xxxxxxxxxxxxxxxxx", "email": "foo@bar.com"}' http://localhost/user/register Currently, I have this…
ncrocfer
  • 2,542
  • 4
  • 33
  • 38
28
votes
5 answers

How to generate OpenApi 3.0 spec from existing Spring Boot App?

I have a project (Spring Boot App + Kotlin) that I would like to have an Open API 3.0 spec for (preferably in YAML). The Springfox libraries are nice but they generate Swagger 2.0 JSON. What is the best way to generate an Open Api 3.0 spec from the…
ladyskynet
  • 297
  • 1
  • 3
  • 10
28
votes
2 answers

How to define constant string in Swagger open api 3.0

How to define constant string variable in swagger open api 3.0 ? If I define enum it would be like as follows "StatusCode": { "title": "StatusCode", "enum": [ "success", "fail" ], "type": "string" …
Harsha Gayan
  • 339
  • 1
  • 5
  • 13
1 2
3
…
99 100