38

I'm just starting using swagger following this guide, but I found out something very weird that makes no sense for me.

As far as I remember , the v2/api-docs should be used for when you have docs of the version number 2 of your API.

So, the default should be only api-docs, but for some strange reason I found that the default is v2/api-docs.

Checking the library doc I found this.

How do I override that value without later not being able to use v2? (when my API will reach a v2 but I will also want to show the legacy docs).

Or maybe my concept of using v2 is wrong? Can someone help me with this?

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
jpganz18
  • 5,508
  • 17
  • 66
  • 115
  • The `v2` in the URL does not refer to your APIs version number, it is the Swagger specification version number. The current version of SpringFox uses Swagger 2.0 by default, this is what you are seeing. – woemler Sep 12 '16 at 14:46

1 Answers1

65

The /v2/api-docs URL is the default that SpringFox uses for documentation. The v2 does not refer to your API's documentation version (which can be changed in the Docket configuration), but the version of the Swagger specification being used. Take a look at the documentation here for customizing the Swagger documentation URL. In short, you need to modify an environment property to change the URL your documentation will appear at:

springfox.documentation.swagger.v2.path=/my/docs

This will change the default URL for the SpringFox Swagger documentation from /v2/api-docs to whatever you specify. To implement this, add the above property to a new or existing properties file, and then add it as a property source in your Springfox configuration class:

@PropertySource("classpath:swagger.properties")
@Configuration
public class SwaggerConfig {...}
woemler
  • 7,089
  • 7
  • 48
  • 67
  • Thanks!. So, this is the endpoint for the swagger documentation only? is not for my API's documentation? how can I set my api's documentation then? – jpganz18 Sep 12 '16 at 14:53
  • 1
    Swagger is a specification for describing API endpoints. What you see at `/v2/api-docs` is the documentation for your API in the Swagger 2.0 standard (as opposed to Swagger 1.0, RAML, RestDocs, etc). You can find more info about the Swagger spec on their website: [http://swagger.io/](http://swagger.io/) – woemler Sep 12 '16 at 14:57
  • 1
    any idea where my API's docs will be if not in v2/api-docs? (because that URL is already taken) will swagger2 generate or give me an URL for it? – jpganz18 Sep 12 '16 at 15:45
  • The Swagger docs are located at whatever the value of the `springfox.documentation.swagger.v2.path` property is, which is `/v2/api-docs` by default. See the updated answer above. – woemler Sep 12 '16 at 15:52
  • but not for the swagger, for my API, I want to have docs for my API itself, where should they be located? – jpganz18 Sep 12 '16 at 15:57
  • I am not totally sure what you are asking for at this point. The docs generated by Springfox ARE the documentation for your API. You can change the endpoint for the docs, as I illustrated in my answer. What that custom endpoint is is completely up to you. If you are having trouble with a separate aspect of the documentation, perhaps you should create another question and link to it. – woemler Sep 12 '16 at 17:40
  • 3
    Is there any solution to change the path for /swagger-ui.html? – Shikha A Mar 23 '18 at 20:49
  • @ShikhaA: Swagger UI is a totally separate package with different configuration. – woemler Mar 24 '18 at 23:54
  • what does the endpoint should return, if I change it to `/my/docs`? Can I return my own swagger.json? – xbmono Aug 09 '19 at 03:44
  • I want to return my own generated swagger.json to be displayed by springfox's swagger-ui.html. Is that achievable with this approach? I did the same thing mentioned here and created an endpoint that returns my own swagger.json as string but swagger-ui still displays APIs that aren't those I am returning... I can see the path is changed to /my/docs but it doesn't initiate my endpoint – xbmono Aug 09 '19 at 04:19
  • @xbmono Have you modified the URL that `swagger-ui` is reading from? You should be able to pint it to your custom URL to read that new json file. – woemler Aug 09 '19 at 13:33
  • @woemler No I didn't want to mess with that html file... I fixed it another way, I ended up creating a new bean `SwaggerResourcesProvider` and only returning my swagger's location. This link: http://springfox.github.io/springfox/docs/current/#aggregating-multiple-swagger-specifications-in-the-same-swagger-ui – xbmono Aug 11 '19 at 23:42