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
27
votes
2 answers

Swagger Codegen (with maven plugin) for OpenAPI 3.0

I want to use Swagger Codegen for OpenAPI 3.0 YAML file. And I see Swagger Codegen 3.0.0-rc0 is available. But when I try to use that I run into issues. Following are the details: My pom.xml file with swagger-codegen plugin: …
Kuldeep Jain
  • 8,409
  • 8
  • 48
  • 73
26
votes
3 answers

OpenAPI - how to describe query parameters?

I'm trying to figure out how to document two of my query parameters in OpenAPI. Filtering My filtering follows the recommendations of JSON:API, which takes the form of, for example: ?filter[post]=1,2,3 ?filter[post]=1,2,3&filter[author]=5 The…
StackOverflowNewbie
  • 39,403
  • 111
  • 277
  • 441
26
votes
2 answers

How to reference array item examples in OpenAPI 3?

Using this schema definition: schemas: AllContacts: type: array items: $ref: '#/definitions/ContactModel1' example: - id: 1 firstName: Sherlock lastName: Holmes - id: 2 firstName: John …
Old Man Walter
  • 629
  • 2
  • 7
  • 16
26
votes
2 answers

How to document dynamic query parameter names in OpenAPI (Swagger)?

Is there any way to document the following query? GET api/v1/users?name1=value1&name2=value where the query parameter names are dynamic and will be received from the client. I'm using the latest Swagger API.
Sharad Ahire
  • 758
  • 2
  • 16
  • 32
26
votes
1 answer

How to write OpenAPI 3 (Swagger) specification for property name in `map` object?

The API I'm trying to describe has a structure where the root object can contain an arbitrary number of child objects (properties that are themselves objects). The "key", or property in the root object, is the unique identifier of the child object,…
user2152081
  • 777
  • 1
  • 9
  • 17
26
votes
2 answers

How to return an array of objects in SwaggerHub?

I am defining an API specification in SwaggerHub using OpenAPI 2.0. The /contacts request returns an array of contacts. The definition is below: /contacts: get: tags: - contacts summary: Get all the contacts …
Krishna Adhikari
  • 357
  • 1
  • 4
  • 9
26
votes
2 answers

"discriminator" in polymorphism, OpenAPI 2.0 (Swagger 2.0)

Referencing OpenAPI 2.0, Schema Object, or Swagger 2.0, Schema Object, and the definition of discriminator field as: Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema…
Musa Haidari
  • 2,109
  • 5
  • 30
  • 53
25
votes
1 answer

Multi-level (nested) tagging in Swagger UI

I just started working on Swagger 2.0 API recently. I am looking for some ways to organize the API documentation. Currently I'm using the @Api(tags = {"Heading1"}) Java annotation to tag each API. The generated documentation looks…
kani mozhi
  • 251
  • 1
  • 3
  • 3
25
votes
2 answers

Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?

I'm having a hard time trying to figure out how I can nest models in OpenAPI 2.0. Currently I have: SomeModel: properties: prop1: type: string prop2: type: integer prop3: type: $ref: OtherModel OtherModel: …
Henrique Barcelos
  • 7,670
  • 1
  • 41
  • 66
24
votes
2 answers

Swagger UI configuration with swagger-config.yaml

As per swagger documentation, Swagger-UI accepts configuration parameters in four locations. From lowest to highest precedence: The swagger-config.yaml in the project root directory, if it exists, is baked into the application configuration object…
Mahendra Kapadne
  • 426
  • 1
  • 3
  • 10
24
votes
1 answer

How to define different responses for same HTTP status code in OpenAPI (Swagger)?

I'm writing an OpenAPI spec for an existing API. This API returns status 200 for both success and failure, but with a different response structure. For example, in the signup API, if the user signed up successfully, the API sends status 200 with the…
Nomura Nori
  • 4,689
  • 8
  • 47
  • 85
23
votes
4 answers

AWS CDK how to create an API Gateway backed by Lambda from OpenApi spec?

I want to use AWS CDK to define an API Gateway and a lambda that the APIG will proxy to. The OpenAPI spec supports a x-amazon-apigateway-integration custom extension to the Swagger spec (detailed here), for which an invocation URL of the lambda is…
John
  • 10,837
  • 17
  • 78
  • 141
22
votes
2 answers

How to define enum mapping in OpenAPI?

I am designing an API and I want to define an enum Severity which can have values LOW, MEDIUM or HIGH. Internally Severity gets stored as an integer so I want to map these to 2,1 and 0 respectively. Is there a way to do this in an OpenAPI…
Yellowjacket
  • 548
  • 2
  • 7
  • 19
22
votes
6 answers

How to generate a PDF or markup from OpenAPI 3.0?

I have an OpenAPI 3.0 spec and I want to generate a PDF out of it so that it can be given to the end users. Currently, tools like swagger-spec-to-pdf or swagger2markup only support Swagger 2.0 but not OpenAPI 3.0. Is it possible to generate a PDF…
Niranjan
  • 517
  • 2
  • 4
  • 21
22
votes
4 answers

OpenAPI (aka Swagger) in Azure Functions V2

I'm creating a V2 Function App and want to use Swagger/Open API for docs, however it is not yet supported in the Azure Portal for V2 Functions. Any suggestions on how I can use Swagger with V2 Functions in VSTS to create the docs on each build?
Albert
  • 255
  • 1
  • 2
  • 8
1 2 3
…
99 100