Software Engineering Stack Exchange
Software Engineering Stack Exchange

Questions tagged [openapi]

The question is about the OpenAPI / Swagger specification.

OpenAPI (formerly Swagger) is a representation of a RESTful API.

From the Swagger website:

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

6 questions
5
votes
2 answers

Semantic Versioning in OpenAPI with string "enum": new values OK?

My team is preparing to add new capabilities to an OpenAPI contract and our implementation of it. There are pre-existing clients. We are planning to take our API from v1.1 to v1.2 while fully respecting semantic versioning. Our team is debating…
wberry
  • 481
  • 3
  • 8
3
votes
1 answer

Share models between AsyncAPI and RESTful APIs?

What I try to solve: Given I run a set of microservices, most of which expose a RESTful API and additionally publish or consume events via messaging broker, and I have decided to go "API first" using OpenAPI and AsyncAPI to specify these APIs, when…
observer
  • 147
  • 7
1
vote
2 answers

Is it OK to return different DTOs for the same endpoint when the user is logged in vs when it is anonymous?

Say that I have a REST endpoint for a chess server. If I'm not logged in and do a GET on /games I could get all running games like: { running_games: [ ..... ] } but if I'm logged in I could get a different representation for that same…
tonicebrian
  • 413
  • 1
  • 4
  • 6
0
votes
0 answers

How to Handle Undocumented Fields in OpenAPI Schema?

I'm working with an API that uses OpenAPI for its schema documentation. However, there are certain fields in the request body that shouldn't be visible to all consumers, for example, internalProperty: bool. These properties are crucial for some…
Sergey Kolesnik
  • 117
  • 5
0
votes
1 answer

Handling OpenAPI Generated code in a Project's repository

In my company, we are would like to recommend OpenAPI and using the design first approach to API development. We would also like to use the OpenAPI Generator to generated server stubs and DTOs from OpenAPI specs. We are using the OpenAPI Generator…
Nullbeans
  • 109
  • 3
0
votes
2 answers

How to keep OpenAPI specification up-to-date and compliant without using code generators?

In our company, there is no standard for how to document APIs. Missing API documentation slows down the development process. Therefore, we want to introduce OpenAPI. We want to use code generators to ensure that the OpenAPI specification is…
Harold L. Brown
  • 207
  • 1
  • 5