So ändern Sie den Standardpfad der Swagger UI-URL

Swagger UI ist ein großartiges Werkzeug zur Visualisierung und Interaktion mit OpenAPI-Spezifikationen. Wenn Sie mit Swagger UI arbeiten, werden Sie feststellen, dass URLs eine wichtige Rolle bei der Konfiguration und dem Zugriff auf die API-Dokumentation spielen. In diesem Beitrag werden wir Swagger UI URLs entmystifizieren, um Ihnen zu helfen, sie effektiver zu nutzen.

Was ist ein Swagger UI?

Swagger UI ist ein Tool, mit dem der Benutzer mit APIs mithilfe der OpenAPI-Spezifikationsdokumentation interagieren kann. Es liest das Spezifikationsdokument und zeigt es in einem visuell interaktiven Format an. Dies hilft Entwicklern, APIs zu verstehen, Testanfragen zu senden, zu debuggen und Ihre REST-APIs zu verwenden.

Die Swagger UI URL entspricht dem Endpunkt, an dem Sie Ihre OpenAPI-Spezifikations-JSON-Datei bereitstellen. Dies bedeutet, dass Sie eine Webadresse angeben müssen, die auf den Speicherort Ihrer OpenAPI-JSON-Datei verweist. Swagger UI liest diese Datei, um eine benutzerfreundliche Oberfläche zu erstellen, die über diese URL zugänglich ist. Die genaue URL-Struktur kann aufgrund unterschiedlicher Serverkonfigurationen variieren.

Swagger UI Funktionen

Swagger UI ist ein leistungsstarkes Tool, das eine Reihe von Funktionen zum Testen, Verstehen und Visualisieren von APIs bietet. Einige Funktionen werden im Folgenden erwähnt:

Hauptmerkmale sind:

• Live-Tests von APIs direkt in den Dokumenten
• Intuitive Steuerung für Anfrageparameter
• Code-Snippet-Generierung für API-Aufrufe
• Markdown-Unterstützung für die Formatierung
• Tools für die Teamzusammenarbeit
• Automatische Datenmodellvisualisierung
• API-Endpunktorganisation und -suche

Swagger UI URL-Parameter

Swagger UI hat verschiedene Parameter in der URL, um sein Verhalten und sein Aussehen zu konfigurieren. Diese beeinflussen, wie die API-Dokumentation mit Swagger UI angezeigt wird. Einige der am häufigsten verwendeten Swagger UI URL-Parameter sind:

URL:

Dies gibt die OpenAPI-Spezifikationsdateien-URL an, die Swagger UI verwenden soll, um die API-Dokumentation zu generieren. Das Format der URL ist wie folgt:

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json

ConfigUrl:

configUrl stellt die URL einer JSON-Konfiguration bereit, die das Verhalten von Swagger UI anpasst und verändert.

http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json

deepLinking:

Es ermöglicht Deep Linking zu einzelnen Operationen oder Tags in der API-Dokumentation. Es ist nützlich, wenn direkte Links zu bestimmten Teilen der Dokumentation freigegeben werden.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true

oauth2RedirectUrl:

Es ermöglicht den Benutzern, nach erfolgreicher Authentifizierung zu einer anderen URL weiterzuleiten, wenn Ihre API OAuth 2.0-Authentifizierung benötigt.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect

defaultModelsExpandDepth:

Es passt die Standardtiefe der Modelle in der Dokumentation an.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2

So finden Sie die Swagger UI URL

Manche Leute sind verwirrt darüber, wo sich die Swagger UI URL befindet. Sie wird basierend auf der Konfiguration Ihres Projekts generiert. Um die URL zu finden, gehen Sie wie folgt vor:

1. Stellen Sie sicher, dass Ihr Projekt so konfiguriert ist, dass es die Swagger-Dokumentation generiert.
2. Um auf die Swagger UI zuzugreifen, müssen Sie die Basis-URL Ihrer API mit dem Swagger-Dokumentationsendpunkt kombinieren. Dies führt zu Ihrer Swagger UI URL.

Wenn Sie beispielsweise Ihre API unter http://localhost:3000 hosten und Ihr Swagger-Endpunkt /swagger-ui/ lautet, wird Ihre Swagger-URL zu http://localhost:8080/swagger-ui/.

Wenn Sie immer noch Probleme haben, Ihre Swagger UI URL zu finden, können Sie sich auf die Dokumentation des Frameworks oder der Bibliothek beziehen, die Sie zum Generieren Ihrer APIs verwenden. Dies hilft bei der Bereitstellung von Informationen zum Zugriff auf die URL für Ihre spezifische Einrichtung.

Wie ändert man den Swagger UI Defauth-Pfad?

Der Standardpfad Ihrer Swagger UI hängt von den Konfigurationen Ihres Servers ab. Er wird basierend auf dem Standort und dem Ort, an dem Sie Swagger UI bereitgestellt haben, erstellt. Die Standard-URL-Pfade können entsprechend den Benutzeranforderungen und der Bereitstellung geändert werden. Der URL-Parameter in der URL sollte auf den Speicherort der OpenAPI-Spezifikationsdatei verweisen.

Es gibt viele Methoden, um den Standardpfad der Swagger UI URL zu ändern.

Ändern der Swagger-Konfigurationsdatei (Apache und Nginx):

Wenn Sie einen Webserver verwenden, können Sie die Konfigurationen Ihres Servers ändern, um Anfragen an einer bestimmten URL zu verarbeiten.

Apache:

Im Fall von Apache können Sie Ihre Konfigurationsdatei ändern, um eine Rewrite-Regel zu erstellen, sodass Anfragen an Ihren Swagger UI-Pfad umgeleitet werden können. Sie müssen Ihre Konfigurationsdatei öffnen, die oft den Namen „httpd.conf“ oder „apache2.conf“ hat. Fügen Sie in dieser Datei Ihre Rewrite-Regel für Ihren gewünschten Pfad hinzu.

RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]

Sie können Ihren Apache-Server neu starten, damit die Änderungen wirksam werden.

Nginx:

Wenn Sie Nginx verwenden, müssen Sie Ihre Serverdateikonfiguration aktualisieren, um einen Speicherort für die Verarbeitung Ihrer Anfragen zu definieren. Fügen Sie in dem Serverblock Ihren Speicherort hinzu.

server {
    listen 80;
    server_name your-domain.com;

    location /api-docs {
        alias /path/to/your/swagger-ui;
        index index.html;
    }
}

Überprüfen Sie nach den Änderungen auf Syntaxfehler und laden Sie Ihr Nginx neu, damit die Änderungen wirksam werden.

Verwenden von Frameworks wie Express.js:

Mit Express.js können Sie Ihre Routen so konfigurieren, dass sie Swagger UI-Anfragen verarbeiten.

Um Swagger UI bereitzustellen, müssen Sie eine Route in Ihrer Express.js-Serverdatei definieren.

const express = require('express');
const app = express();

app.use('/custom-path', express.static('swagger-ui'));

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Auf diese Weise können Sie über Ihren „custom-path“ auf Ihre Swagger UI zugreifen.

Nutzung von Springboot, um den Standardpfad zu ändern:

In einer Spring Boot-Anwendung können Sie die Dateien „application.properties“ oder „application.yml“ ändern. Sie können die folgende Eigenschaft hinzufügen, um den Standard-Swagger UI-Pfad in Ihren Dateien „application.properties“ oder „application.yml“ zu ändern.

springfox.documentation.swagger-ui.path=/custom-path

Sie können „/custom-path“ entsprechend Ihrem gewünschten Pfad ersetzen.

Als Nächstes müssen Sie Bean konfigurieren, um den Pfad anzupassen. Sie können „WebMvcConfigurerAdapter“ erweitern, um dies zu erreichen.

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
    }
}

Stellen Sie sicher, dass Sie die erforderlichen Abhängigkeiten in Swagger haben, um diese Ergebnisse zu erzielen.

Dann müssen Sie die Hauptklasse Ihrer Anwendung konfigurieren.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.package.name"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Your API Documentation")
                .version("1.0")
                .build();
    }
}

Ersetzen Sie „your.package.name“ durch das Basispaket Ihrer Controller.

Swagger UI-Initialisierung:

Sie können den Parameter „url“ anpassen, um Ihren gewünschten URL-Pfad widerzuspiegeln. Auf diese Weise können Sie den Standardpfad von Swagger UI ändern. Bei der Initialisierung von Swagger UI in JavaScript können Sie die folgenden Änderungen vornehmen.

const ui = SwaggerUIBundle({
  url: "/custom-path/swagger.json", 
});

Verwenden von Swagger UI zum Testen von APIs

Ähnlich wie andere API-Testtools, wie z. B. Apidog, bietet Swagger UI eine effiziente und benutzerfreundliche Möglichkeit, APIs zu testen. Sie müssen bestimmte Schritte ausführen, um Ihre APIs mithilfe der Swagger -Website zu debuggen und zu testen. Klicken Sie auf Live-Demo und beginnen Sie mit der Erkundung von Swagger UI. Sie sehen ein Fenster wie dieses geöffnet.

Sie können mehrere HTTP/HTTPS-Methoden wie POST, GET, PUT usw. erkunden.

Sie können auf eine beliebige Methode klicken und sich umsehen. Wenn Sie auf die POST-Methode klicken, sehen Sie eine Option zum Hochladen eines Bildes und zum Aktualisieren der Parameter der Methode. Sie können auf „Ausführen“ klicken, und Ihre Anfrage wird ausgeführt.

Sie können die Antwort auf die POST-Anfrage sehen, indem Sie nach unten scrollen.

In ähnlicher Weise können Sie mit anderen angegebenen Methoden arbeiten und sehen, was sie tun. Dies gibt Ihnen eine gute Vorstellung davon, wie Swagger UI funktioniert.

Erwägen Sie Apidog für eine robustere API-Dokumentation, die über die Fähigkeiten von Swagger UI hinausgeht. Apidog ermöglicht das vollständige API-Lifecycle-Management, einschließlich Design, Mocking, Testen, Versionierung, Zusammenarbeit und mehr.

Mit erweiterten Funktionen wie CI/CD-Integration und Team-Workflows bietet Apidog ein umfassenderes Toolkit zur Straffung der API-Bereitstellung. Seine umfassende Plattform skaliert die API-Entwicklung und verbessert die Produktivität.

Fehlerbehebung bei Swagger UI Localhost

Wenn Sie Probleme mit der Swagger UI URL auf localhost haben, gibt es mehrere Schritte zur Fehlerbehebung, die Sie untersuchen können, um das Problem zu diagnostizieren und zu beheben.

1. Stellen Sie sicher, dass Ihr API-Server läuft. Swagger UI kann die Dokumentation nicht abrufen, wenn Ihr Server Probleme beim Ausführen hat.
2. Überprüfen Sie Ihre Swagger-Konfigurationen, um festzustellen, ob sie korrekt eingerichtet sind.
3. Verwenden Sie die richtige Swagger UI URL mit den richtigen Endpunkten.
4. Leeren Sie den Cache Ihres Browsers. Manchmal können unerwartete Fehler mit zwischengespeicherten Daten auftreten.
5. Starten Sie sowohl Ihren API-Server als auch Ihren Browser neu, nachdem Sie Änderungen vorgenommen haben.
6. Überprüfen Sie das URL-Format, das Sie für den Zugriff auf Swagger UI verwenden, noch einmal.

Fazit

Zusammenfassend lässt sich sagen, dass Swagger UI aufgrund seiner breiten API-Verwaltungstechniken bei Entwicklern schnell an Popularität gewinnt. Es bietet eine gut strukturierte Dokumentation und eine benutzerfreundliche Oberfläche. Benutzer können auch Datenmodelle visualisieren, während sie Live-API-Tests durchführen, was es zu einer guten Wahl für API-Tests und -Debugging macht.

Obwohl Swagger UI seine Vorteile hat, gibt es auch einige Einschränkungen, die der Benutzer beim Testen von APIs sehen kann. Es bietet eine begrenzte Zusammenarbeit zwischen Entwicklern und unterstützt keine Integration mit anderen API-Verwaltungstools.