Swagger-core: swagger 2.0 why api description has been deprecated ?

[tokra]

Hello in new swagger there is description deprecated, and if using new UI, its completely missing next to api. Who made this decission ?

[webron]

It was deprecated, but there's an alternative solution. From https://github.com/swagger-api/swagger-core/wiki/1.3--1.5-Migration#setting-up-additional-information-authorization-info:

One addition is the Tag. As explained in a previous section, grouping is now done using tags. While tags are generated automatically as they are declared, you may wish to add more information on the tags. You can set a description (which in 1.3 was automatically derived from the code, but no more) and you can add additional information in a form of external documentation.

[tokra]

@webron From your code there is see that tags are the setup programatically, but for portability we are trying to avoid programatical approach on one place if possible, so better using annotation -> do you have some example to setup tags by annotation ? thanks

[webron]

Right now, the only way to set it up is programmatically.

[tokra]

@webron well this is the thing which makes it useless :( I think it wouldnt be big problem to implement new annotation @ApiTags or something...

Pardon me but: Deprecating stuff and not implementing new way is contra-productive (maybe not for you but for companies & guys using your swagger and depending on you)

Hope you understand my thoughts

[webron]

Hmpf, I've rushed into the answer, sorry about that. You can use the @SwaggerDefinition to set it up. Please have a look at https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#swaggerdefinition.

Also, it wasn't deprecated without an alternative way, it was given an alternative way that you may not like. The functionality wasn't just taken away. The reason it was deprecated is that the way APIs are grouped in Swagger 2.0 is significantly different than previous versions. Keeping it the way it was would have meant dealing with potential conflicts and that's something we wanted to avoid for the sake of our users.

[fehguy]

I'm closing this since we have the @SwaggerDefinition as @webron stated.

[tokra]

@SwaggerDefinition & @Api are different things. If i use @SwaggerDefinition on API Resource, it produces completely different things !

[tokra]

I wanted to add description next to API as it was in previous version of swagger, but if i use your mentioned @SwaggerDefinition it produces some text added on TOP before all apis listing. Please how to achieve same description as was before ? I am expecting normal answer or some example, until now i did not get that. thank you in advance

[tokra]

What if you rather add @Info also into @Api annotation to make it clear ?

[webron]

@to-kra - sorry for the confusion, I'll try to be clearer.

In the previous version of swagger-core (that is, 1.3.X), it produced Swagger specs of version 1.2. In Swagger 1.2, operations were grouped under _resources_, and each resource had its own description. When it came to java code, a resource and a jax-rs endpoint had a 1:1 relation. When that was the case, @Api#description() was used as the description of that resource.

swagger-core 1.5 exposes Swagger 2.0 which changed the operation organization slightly. Now, the operations are grouped under tags (which can be zero or more tags per operation). As it is now, there isn't necessarily a 1:1 relation between a jax-rs resource and a tag. In fact, multiple jax-rs resources can use the same tag. As such, we can no longer depend on the @Api#description() for it because if they'd represent the same tag, the values would clobber each other and we'd have no real way of choosing the 'right' description.

The end result was that we had to come up with another way to add the metadata for the tags. Right now there are two ways to do so - first, using the @ApiDefinition and the second is by directly manipulating the Swagger object.

[aperinot-orange]

I don't know where you found your "@ApiDefinition" annotation, but certainly not in swagger related code.
So the only remaining solution, is to write a SwaggerDefinition.

We're writing SwaggerDefinition for so much elements is the current version of swagger-annotations, that we start to wonder if swagger-annotations is still the way to go...

[qqin005]

I have tried to add description via SwaggerDefinition, but it's not working.

@SwaggerDefinition(tags = {
        @Tag(name = "foo", description = "Operations about foo")
})

[shamseertk]

@Api description attribute was working for me. I dont see any alternative for that. I even tried SwaggerDefinition. Any help would be great.

[pandyamitesh]

SwaggerDefinition is not working

Tried -
@SwaggerDefinition(tags = {@Tag(name = "My Swagger Resource", description = "Meaningful stuff in here")})

[spyro2000]

Same problem here. Only @Api is working for me, all other annotations are simply ignored when producing the swagger.json/yaml. If you deprecate something, please provide a working alternative.

[ErgoSoftUK]

@pandyamitesh / @spyro2000 - as well as adding the tag definition into the @SwaggerDefinition, are you also adding the tag reference into @Api?

@SwaggerDefinition(
    tags = {
        @tag(name = "Tag1", description = "Description for tag 1")
    }
)

@Api(tags = {"Tag1"})
public class MyEndpoint {....

[RestfulBlue]

i also facing this issue, combining @Api and @SwaggerDefinition does not work

[robo3945]

Same problem for me: @Api and @SwaggerDefinition combined do not work.

[satishpatro44]

it is getting ignored

@Api(value = "Employee Management System", description = "ABCD")
public class UserController {

is showing UserController ABCD, but description is depreceated

@Api(value = "Employee Management System", description = "ABCD", tags = {
    "Tag1" })
@SwaggerDefinition(tags = { @Tag(name = "Tag1", description = "Operations about foo") })
public class UserController {

is showing Tag1 ABCD

@Api(value = "Employee Management System", tags = {
    "Tag1" })
@SwaggerDefinition(tags = { @Tag(name = "Tag1", description = "Operations about foo") })
public class UserController {

is showing UserController UserController

Any alternative?

[robo3945]

it's a little bit frustrating to not have a way to put a description on a Controller Class...

[lassounski]

Is this issue from 2015 still opened? 😪

[robo3945]

I'm using SpringBoot last release (and swagger dependencies too) and yes I
cannot decorate a class with reasonable description in Swagger

Il giorno mer 25 set 2019 alle ore 11:03 Kirill Lassounski <
[email protected]> ha scritto:

Is this issue from 2015 still opened? 😪

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/swagger-api/swagger-core/issues/1476?email_source=notifications&email_token=AD6EULJQLJGEUEGIE3T24JDQLMSN5A5CNFSM4BRKAFLKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7RFHPI#issuecomment-534926269,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AD6EULITXI6PXIRRRYWP6QTQLMSN5ANCNFSM4BRKAFLA
.

[lassounski]

I'm using SpringBoot last release (and swagger dependencies too) and yes I cannot decorate a class with reasonable description in Swagger Il giorno mer 25 set 2019 alle ore 11:03 Kirill Lassounski < [email protected]> ha scritto:
…
Is this issue from 2015 still opened? 😪 — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1476?email_source=notifications&email_token=AD6EULJQLJGEUEGIE3T24JDQLMSN5A5CNFSM4BRKAFLKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7RFHPI#issuecomment-534926269>, or mute the thread https://github.com/notifications/unsubscribe-auth/AD6EULITXI6PXIRRRYWP6QTQLMSN5ANCNFSM4BRKAFLA .

Oh man! That's so annoying.
I got SonarQube complaining on my ass because I am using deprecated stuff 😰

[satishpatro44]

Do I need to open new Issue as this issue is closed?

[ramazankaragoz]

I have tried to add description via SwaggerDefinition, but it's not working.

@SwaggerDefinition(tags = {
        @Tag(name = "foo", description = "Operations about foo")
})

I have same problem.What is this solution ? Can someone show me an example ? SonarLint gives an error as deprecated..

[anandvarkeyphilips]

https://github.com/springfox/springfox/issues/1940#issuecomment-317921589

This worked for me!

@Api(tags = {"tag"}) on Controller and

@Bean public Docket commonDocketConfig() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.company")) .paths(PathSelectors.any()) .build() .apiInfo(apiEndPointsInfo()) .tags(new Tag("tag", "description")); }

[electrocnic]

Would be nice if

@SwaggerDefinition(tags = {
        @Tag(name = "foo", description = "Operations about foo")
})

would just work as expected. Can someone finally fix this please? It's been 5 years already!

[mjustin]

Since this issue is closed, and is phrased as a question rather than a feature request/bug fix, I've created a separate issue for fixing the @SwaggerDefinition solution discussed here.

3737