Forum Discussion

Syntax0111's avatar
Syntax0111
New Contributor
4 years ago

Swagger Editor and Supporting Services

Hello,   I have been successful in running Docker containers for Swagger UI and Swagger Editor, from swaggerapi/swagger-ui and swaggerapi/swagger-editor (pulled from DockerHub), respectively. This ...
Swagger Codegen
Swagger Core
Swagger Editor
Swagger UI
ponelat's avatar
ponelat
Staff

The Docker image for SwaggerEditor is missing support for overriding configuration at the moment. There are two (old) issues that track that:

- https://github.com/swagger-api/swagger-editor/issues/1488

- https://github.com/swagger-api/swagger-editor/issues/1547

 

It'd be great if you were interested in pushing any of those issues forward, as it's not a high priority for the core contributors at the moment. 

 

One way to achieve your goal is to override the default index.html, with the new URL configured in it.

Something like

 

docker run -it --rm -p 8080:8080 -v "$(pwd)/index.html:/usr/share/nginx/html/index.html" swaggerapi/swagger-editor

 

Where `$(pwd)` is the directory where your copy of index.html. 

The official index.html is here: https://github.com/swagger-api/swagger-editor/blob/master/index.html.

And an example with the URLs overwritten can be found here: https://gist.github.com/ponelat/a63e894c87fdc626b520c69aa13ccba7#file-index-html-L56-L58 

Syntax0111's avatar
Syntax0111
New Contributor
4 years ago

So far, this works great locally. Thank you so much for the reply ponelat!

 

However, when attempting to deploy this behind an HTTPS connection, I get the following 'Secure Connection Failed' Error code:

 

SSL_ERROR_RX_RECORD_TOO_LONG

 

Is there anything special I need to do to instantiate the following containers in order to avoid this error:

 

swaggerapi/swagger-validator-v2

swaggerapi/swagger-converter

 

Thanks again!

 

 

 

  • ponelat's avatar
    ponelat
    Staff
    4 years ago

    Hi Syntax0111 

     

    Glad the example works.

    Not sure what can be done about the SSL error, there isn't any built-in SSL for those containers so it'll be a configuration on your HTTPS termination point (nginx/apache/etc). However there are some redirect configurations you can try, see https://github.com/swagger-api/validator-badge#swagger-validator-badge- for more details.

     

    Another point of caution is to ensure you're going to the right port.

     

     

    • Syntax0111's avatar
      Syntax0111
      New Contributor
      4 years ago

      Hello ponelat, after speaking to my peer, the SSL error turned out to be a NAT configuration issue which we were able to take care of, thank you. We now have instances of the supporting services listed below running in our test environment using the Docker containers from Docker Hub:

       

      swaggerapi/swagger-validator-v2

      swaggerapi/swagger-converter

       

      However, I am still facing some challenges with these services when requesting validation/conversion to an API definition that is hosted on the same server.

       

      While the sample https://petstore.swagger.io/v2/swagger.json validates with our instance of the validator badge and converts properly to OpenAPI 3.0 with the converter, I can't seem to validate any APIs definitions that are hosted on the same server, albeit different ports, for example, the following succeeds:

       

      https://example.test.host.com:8050/validator/?url=https://petstore.swagger.io/v2/swagger.json, and

      https://example.test.host.com:8051/api/convert/?url=https://petstore.swagger.io/v2/swagger.json

       
      But, the following request against an internal API's definition hosted on the same server, fails to validate and convert:
       
      https://example.test.host.com:8050/validator/?url=https://example.test.host.com:8052/api/swagger.json (fails validation)
      https://example.test.host.com:8051/api/convert/?url=https://example.test.host.com:8052/api/swagger.json (fails conversion)
       
      The validator badge fails with the error "Can't read from file https://example.test.host.com:8052/api/swagger.json" with an HTTP status code of 400 Bad Request.
       
      The converter fails with something similar: "Unable to read location 'https://example.test.host.com:8052/api/swagger.json'" with the same status.
       
      Here is a bit more detail on our current setup and where we are trying to go with this:
       
      We are trying to implement Swagger Opensource tools using the Dockerized services available in Docker Hub to view and author OpenAPI compliant definition files.
       
      So far, we have an instance of Swagger UI running to serve as our API catalog accomplished by using the URLS environment variable as described in the documentation (https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md) with URLs to some of our internal APIs that sit on the same server but on different ports. This works great and the UI has a drop down list to choose the APIs definition to render. Our next goal is to point our instance of Swagger UI to validate with our local validator instance since it's currently disabled.
       
      The Swagger Editor's File > Import URL works great with the addresses to the internal API's definition as well, but although we were able to configure the Editor to point to our internal converter, the converter is unable to read definition as described above.
       
      One difference I noticed between the two containers that worked for us, Swagger UI and Editor and the two that are not working for us, is the port configuration the containers are configured with. While Swagger UI and Editor have the following configuration:
       
      PORTS    NAMES
      80/tcp, 0.0.0.0:aaaa->8080/tcp    swagger-ui
      80/tcp, 0.0.0.0:bbbb->8080/tcp    swagger-editor
       
      The validator and converter look as follows:
       
      PORTS    NAMES
      0.0.0.0:cccc->8080/tcp    swagger-validator
      0.0.0.0:dddd->8080/tcp    swagger-converter

       

      Any ideas on the reason the validator/converter can't read internally exposed definitions would be greatly appreciated.

       

      Thanks again!

      • ponelat's avatar
        ponelat
        Staff
        4 years ago

        Hey Syntax0111 

         

        I'm not entirely sure as these issues are more related to your networking than to Swagger itself.

        It does sound like your internal services are not public, and because SwaggerUI makes calls from the browser (there is no sever component), it may not be able to reach your internal services.

         

        SwaggerUI (and the user's browser running SwaggerUI) will need to be able to reach your internal services. You could expose them publicly, or else you may need to consider using a VPN or other authentication methods (HTTP Basic as a crude alternative).