Do we have to manually configure api endpoint in openapi 2.0?

user_18156426 0
Viewed 131

I am new to Java. I am working on a legacy app that uses openapi 2.0 for swagger. I added a new controller with 2 api endpoints. Those 2 api endpoints are not showing up in swagger-ui. I see the entries for existing endpoints in openapi.json. I am trying my best not to manually edit openapi.json. Do we have to manually configure api endpoints in openapi.json version2.0 for it to show up in swagger ui? We use gradle to build our project. I re-built the project, but no luck.

Most of the tutorial seems to be for openapi 3.0, not 2.0. openapi 3.0 seems to auto generate all the endpoints in swagger-ui, but not sure if 2.0 does that.

swagger-ui swagger openapi gradle java
1 Answers

Most of the tutorial seems to be for openapi 3.0, not 2.0

Yes, 3.x is the latest version. The versions from 3.0 onwards are called OpenAPI. The ones prior to 3.0 are called Swagger for historical reasons.

openapi 3.0 seems to auto generate all the endpoints in swagger-ui, but not sure if 2.0 does that.

Your problem is not related to the version of your specification. You always want your API specification to be in sync with your implementation. Therefore you need to decide what's your source of thruth, your API spec or your code. So choose an approach:

  • Either you generate code from your specification, for example by following this tutorial. From the generated code, you can have the Swagger UI documentation auto-generated as well. There are several code generators for OpenAPI, you have to choose one.
  • Or you manually write your code, based on your spec of course. Based on annotations, you can have the documentation created. That approach is explained here, for example.

Based on your statements

I added a new controller with 2 api endpoints. [...] I am trying my best not to manually edit openapi.json

I assume that you go with the second approach. So you best look into how your documentation gets auto-generated at the moment, to ensure your new endpoints are also shown. Further judgement of what is wrong is not possible based on what you have asked.

user_17466850
Related