Swagger docs page with custom URL

[auerl]

Hi all,

I am trying to generate a swagger docs page for a REST API based on express.js and the serverless framework. In serverless.yml we specified the following serverless-auto-swagger config parameters:

  apiDomains:
    dev: api-dev.boum.us
    prod: api.boum.us 
  autoswagger:
    title: 'Boum API'
    generateSwaggerOnDeploy: true
    host: ${self:custom.apiDomains.${opt:stage, self:provider.stage}}
    useStage: false

Now when I deploy to stage dev using sls deploy I get the following output:

✔ Service deployed to stack boum-api-dev (123s)

endpoints:
  GET - https://y5d2vybjm0.execute-api.eu-central-1.amazonaws.com/swagger
  GET - https://y5d2vybjm0.execute-api.eu-central-1.amazonaws.com/swagger.json
  GET - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices/{deviceid}
  POST - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices
  DELETE - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices/{deviceid}
  PATCH - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices/{deviceid}
  GET - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices
  GET - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/devices/{deviceid}/data
  POST - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/auth/signup
  POST - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/auth/signin
  POST - https://s737djx1rf.execute-api.eu-central-1.amazonaws.com/dev/v1/auth/token
functions:
  device: boum-api-dev-device (58 MB)
  auth: boum-api-dev-auth (58 MB)
  iotshadowhook: boum-api-dev-iotshadowhook (58 MB)
  iotdatahook: boum-api-dev-iotdatahook (58 MB)
  iotalertshook: boum-api-dev-iotalertshook (58 MB)
  s3firmwarehook: boum-api-dev-s3firmwarehook (58 MB)
  swaggerUI: boum-api-dev-swagger-ui (58 MB)
  swaggerJSON: boum-api-dev-swagger-json (58 MB)
Serverless Domain Manager:
  Domain Name: api-dev.boum.us
  Target Domain: d3vf5mur0y6s4u.cloudfront.net
  Hosted Zone Id: Z2FDTNDATAQYW2

The swagger docs page is available under https://y5d2vybjm0.execute-api.eu-central-1.amazonaws.com/swagger but not, as I would expect, under https://api-dev.boum.us/swagger

Any idea why that is? What do I need to do to make it available under the custom domain name?

Thanks much in advance!

[bfaulk96]

Can you try changing host to

    host: 'https://${self:custom.apiDomains.${opt:stage, self:provider.stage}}'

[bfaulk96]

But also, is there a reason you're specifying the host explicitly? It looks like, for your use-case, you're trying to use the same host/domain as the rest of your serverless functions, which is default behavior. Could you try without the host parameter entirely if the above suggestion doesn't work?

[yehonadav-feel]

@bfaulk96 i also face the same issue. prefixing the host with https://... doesn't work: and it also f@ks up the swagger when you don't enter via your custom domain: removing the host also doesnt work

[arsene-riaworx]

Also having the same issue. The plugin generates its own host and uses that in the swagger docs, which is misleading! Anyone got a solution for this yet? Leaving out the host does work as well.

But also, is there a reason you're specifying the host explicitly? It looks like, for your use-case, you're trying to use the same host/domain as the rest of your serverless functions, which is default behavior. Could you try without the host parameter entirely if the above suggestion doesn't work?

[bfaulk96]

Hey all, just wanted to let you know that I do not know of a solution for this. I didn't write the original plugin, I just wanted to expand on its initial features a bit so I became a maintainer. I don't have a deep understanding of Serverless so I am quite clueless on how this problem would even be addressed, and unfortunately with my new job, I don't really have as much time to explore this plugin. We're happy to look at contributions from the community, but just being very transparent, Sam (the original plugin creator) and I are both very busy and are unlikely to do much active development on this anymore (I don't even use Serverless at my new job, which means my existing knowledge will continue to shrink as well).

[DadUndead]

@auerl @arsene-riaworx Hi guys, I've just faced the same issue. I figured out that it's caused by http and httpApi differences. You need to use the same API type for your endpoints and for swagger. Setting autoswagger.apiType to 'http' solved the issue.

[ralcorta]

@auerl @arsene-riaworx Hi guys, I've just faced the same issue. I figured out that it's caused by http and httpApi differences. You need to use the same API type for your endpoints and for swagger. Setting autoswagger.apiType to 'http' solved the issue.

I had the same problem, and I did that. I'm using [serverless custom domain] (https://github.com/amplify-education/serverless-domain-manager) to attach my domain to my API. I got two api gateway configurations for the same domain. That was happening because I had been using different ApiTypes. I left the customDomain configuration as default (uses REST type) and auto-swagger with apiType: 'http'.

{
// ...
    customDomain: {
        domainName: 'api.example.com',
        certificateName: 'api.example.com',
        // apiType: 'http',
        createRoute53Record: true,
        createRoute53IPv6Record: true,
        autoDomain: true
    },
    autoswagger: {
        title: 'Sls app',
        apiType: 'http',
        generateSwaggerOnDeploy: false,
        swaggerPath: 'swagger',
        apiKeyHeaders: ['Authorization'],
        useStage: false,
        basePath: '/${sls:stage}',
        schemes: ['http', 'https'],
        excludeStages: ['test', 'prod', 'production'],
        useRedirectUI: true
    }
// ...
}