How to generate two different versions of docs?

[disappearer]

I've been looking all over the docs and issues and couldn't find anything related to my issue. We would like to be able to somehow generate two versions of api docs, where some endpoints are omitted in the second version, which will be served publicly. Is it possible?

[oneart-dev]

Also looking for this option. Splitting routes by tags will be ideal solution

[ubogdan]

You can generate 2 documents from 2 different main.go files.

[oneart-dev]

@ubogdan How to tell swag what he should include. Currently I'm using 2 routes per 1 endpoint if it accessible publicly and internally. But it's generate way too many rows for 1 endpoint because of using tags: api, publicApi

I tried to create comments just for public api without code in file but it seems like swag ignoring it

[ubogdan]

I was proposing to have two main files like the following directory structure

cmd/public/main.go
cmd/private/main.go

Both main.go files needs to include the controllers you want to expose in your API. After that, you need to run the following commands in the project root

swag init -g cmd/public/main.go 
swag init -g cmd/private/main.go --instanceName private

Depending on what HTTP mux router you use (echo-swagger, gin-swagger, http-swagger), you may need to register the "swagger"(the default instance name) or the "private" instance name to your router. You can look at the example based on gin-swagger.

I tried to create comments just for public api without code in file but it seems like swag ignoring it

That file needs to be referenced by the main. go or the modules used in it. I never tried that path so I can't give you more hints here.

[oneart-dev]

@ubogdan thank you. I understand the approach but it looks like the overhead is huge.

Firstly there is no any separation inside our code base. All the code is the same. The only difference between public and private endpoints is just the different way to authorization (JWT vs generated api key).

In order to maintain 2 separate docs devs should update and check 2 almost identical controller annotation for same endpoint. For small project it can be possible but when endpoints count pass 100-200 its a bad idea to implement.

The idea I have is to split one file to public and one for private using tags but removing models will be a pain.

Maybe the best approach is provide some kind of modifiers as custom function for swag.

For example:

swag init --customNameResolver /path/to/function.go

func customNameResolver(some swag config and controller annotation) {
    return swagFileName
}

not sure if it's possible but will open more possibilities for developers

[oguzhancagliyan]

any update on this besides creating a separated main.go file?

[meesvandongen]

Depending on your use case it may be possible to further process the output file using another tool such as https://www.npmjs.com/package/openapi-format#openapi-filter-options