Swagger UI URL Varsayılan Yolunu Nasıl Değiştirilir

Swagger UI, OpenAPI spesifikasyonları görselleştirmek ve onlarla etkileşim kurmak için harika bir araçtır. Swagger UI ile çalışırken, URL'lerin API dokümantasyonunu yapılandırmada ve erişimde önemli bir rol oynadığını fark edeceksiniz. Bu yazıda, Swagger UI URL'lerini daha etkili bir şekilde kullanmanıza yardımcı olmak için onları basitleştireceğiz.

💡

Apidog sizin için güçlü bir API dokümantasyon aracıdır. Swagger UI URL önekini ve diğer parametreleri görsel arayüzde kolayca özelleştirebilirsiniz. Hadi deneyelim!

button

Swagger UI Nedir?

Swagger UI, kullanıcının OpenAPI Şartnamesi dokümantasyonunu kullanarak API'lerle etkileşim kurmasını sağlayan bir araçtır. Şartname belgesini okur ve görsel olarak etkileşimli bir formatta görüntüler. Bu, geliştiricilerin API'leri anlamalarına, test istekleri göndermelerine, hata ayıklamalarına ve REST API'lerinizi kullanmalarına yardımcı olur.

Swagger UI URL'si, OpenAPI spesifikasyon JSON dosyanızı sunduğunuz uç noktaya karşılık gelir. Bu, OpenAPI JSON dosyanızın konumuna işaret eden bir web adresi sağlamanız gerektiği anlamına gelir. Swagger UI, bu dosyayı okuyarak o URL üzerinden erişilebilen kullanıcı dostu bir arayüz oluşturur. Tam URL yapısı, farklı sunucu yapılandırmaları nedeniyle değişiklik gösterebilir.

Swagger UI Özellikleri

Swagger UI, API'leri test etmek, anlamak ve görselleştirmek için bir dizi özellik sunan güçlü bir araçtır. Bazı özellikler aşağıda belirtilmiştir:

Temel özellikler şunları içerir:

Doğrudan dokümanlar içinde API'lerin canlı testi
İstek parametreleri için sezgisel kontroller
API çağrıları için kod parçacığı oluşturma
Biçimlendirme için Markdown desteği
Ekip işbirliği için araçlar
Otomatik veri modeli görselleştirme
API uç noktası organizasyonu ve arama

Swagger UI URL Parametreleri

Swagger UI, davranışını ve görünümünü yapılandırmak için URL'de çeşitli parametrelere sahiptir. Bunlar, API dokümantasyonunun Swagger UI kullanılarak nasıl görüntülendiğini etkiler. En sık kullanılan Swagger UI URL parametrelerinden bazıları şunlardır:

URL:

Bu, Swagger UI'nin API dokümantasyonunu oluşturmak için kullanması gereken OpenAPI spesifikasyon dosyası URL'sini belirtir. URL'nin formatı aşağıdaki gibidir:

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

ConfigUrl:

configUrl, Swagger UI'nin davranışını özelleştiren ve değiştiren bir JSON yapılandırmasının URL'sini sağlar.

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

deepLinking:

API dokümantasyonunda bireysel işlemlere veya etiketlere derin bağlantı sağlar. Dokümantasyonun belirli bölümlerine doğrudan bağlantılar paylaşırken faydalıdır.

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

oauth2RedirectUrl:

API'niz OAuth 2.0 kimlik doğrulaması gerektirdiğinde, kullanıcıların başarılı kimlik doğrulamasından sonra başka bir URL'ye yönlendirilmesini sağlar.

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

defaultModelsExpandDepth:

Dokümantasyondaki modellerin varsayılan derinliğini ayarlar.

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

Swagger UI URL'si Nasıl Bulunur?

Bazı insanlar Swagger UI URL'sinin nerede olduğu konusunda kafası karışıyor. Projenizin yapılandırmasına göre oluşturulur. URL'yi bulmak için şu adımları izleyin:

Projenizin Swagger dokümantasyonu oluşturacak şekilde yapılandırıldığından emin olun.
Swagger UI'ye erişmek için, API'nizin temel URL'sini Swagger dokümantasyon uç noktasıyla birleştirmeniz gerekir. Bu, Swagger UI URL'nizle sonuçlanacaktır.

Örneğin, API'nizi http://localhost:3000 adresinde barındırıyorsanız ve swagger uç noktanız /swagger-ui/ ise, Swagger URL'niz http://localhost:8080/swagger-ui/ olacaktır.

Hala Swagger UI URL'nizi bulmakta sorun yaşıyorsanız, API'lerinizi oluşturmak için kullandığınız çerçeve veya kitaplığın dokümantasyonuna başvurabilirsiniz. Bu, kurulumunuza özel URL'ye nasıl erişileceği hakkında bilgi sağlamaya yardımcı olacaktır.

Swagger UI Varsayılan Yolu Nasıl Değiştirilir?

Swagger UI'nizin varsayılan yolu, sunucunuzun yapılandırmalarına bağlıdır. Konuma ve Swagger UI'yi nereye dağıttığınıza göre oluşturulur. Varsayılan URL yolları, kullanıcı gereksinimlerine ve dağıtıma göre değiştirilebilir. URL'deki URL parametresi, OpenAPI spesifikasyon dosyasının konumuna işaret etmelidir.

Swagger UI URL'sinin varsayılan yolunu değiştirmenin birçok yöntemi vardır.

Swagger yapılandırma dosyasını değiştirme (Apache ve Nginx):

Bir web sunucusu kullanıyorsanız, istekleri belirli bir URL'de işlemek için sunucunuzun yapılandırmalarını değiştirebilirsiniz.

Apache:

Apache durumunda, isteklerin Swagger UI yolunuza yönlendirilebilmesi için bir yeniden yazma kuralı oluşturmak üzere yapılandırma dosyanızı değiştirebilirsiniz. Genellikle 'httpd.conf' veya 'apache2.conf' olarak adlandırılan yapılandırma dosyanızı açmalısınız. Bu dosyada istediğiniz yol için yeniden yazma kuralınızı ekleyin.

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

Değişikliklerin yansıması için Apache sunucunuzu yeniden başlatabilirsiniz.

Nginx:

Nginx kullanıyorsanız, isteklerinizi işlemek için bir konum tanımlamak üzere sunucu dosyası yapılandırmanızı güncellemelisiniz. Sunucu bloğuna konumunuzu ekleyin.

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

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

Değişiklikleri yaptıktan sonra herhangi bir sözdizimi hatası olup olmadığını kontrol edin ve değişikliklerin yansıması için Nginx'inizi yeniden yükleyin.

Express.js gibi çerçeveleri kullanma:

Express.js kullanarak, Swagger UI isteklerini işlemek için rotalarınızı yapılandırabilirsiniz.

Swagger UI'ye hizmet vermek için, Express.js sunucu dosyanızda bir rota tanımlamanız gerekir.

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');
});

Bu, Swagger UI'nize 'custom-path' üzerinde erişmenizi sağlayacaktır.

Varsayılan yolu değiştirmek için Springboot'tan yararlanma:

Bir Spring Boot uygulamasında, 'application.properties' veya 'application.yml' dosyalarını değiştirebilirsiniz. 'application.properties' veya 'application.yml' dosyalarınızda varsayılan Swagger UI yolunu değiştirmek için aşağıdaki özelliği ekleyebilirsiniz.

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

'/custom-path' ifadesini istediğiniz yola göre değiştirebilirsiniz.

Ardından, yolu özelleştirmek için bean yapılandırmanız gerekir. Bunu başarmak için 'WebMvcConfigurerAdapter'ı genişletebilirsiniz.

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");
    }
}

Bu sonuçları elde etmek için Swagger'da gerekli bağımlılıklara sahip olduğunuzdan emin olun.

Daha sonra, uygulamanızın ana sınıfını yapılandırmanız gerekir.

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();
    }
}

“your.package.name” ifadesini denetleyicilerinizin temel paketiyle değiştirin.

Swagger UI Başlatma:

'url' parametresini, istediğiniz URL yolunu yansıtacak şekilde ayarlayabilirsiniz. Bu, Swagger UI'nin varsayılan yolunu değiştirmenize olanak tanır. JavaScript'te Swagger UI'yi başlatırken, aşağıdaki değişiklikleri yapabilirsiniz.

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

API'leri Test Etmek için Swagger UI Kullanma

Apidog gibi diğer API test araçları gibi, Swagger UI da API'leri test etmek için verimli ve kullanıcı dostu bir yol sağlar. Swagger sitesini kullanarak API'lerinizi hata ayıklamak ve test etmek için belirli adımları izlemelisiniz. Canlı Demoya tıklayın ve Swagger UI'yi keşfetmeye başlayın. Şuna benzer bir pencerenin açıldığını göreceksiniz.

POST, GET, PUT vb. gibi çoklu HTTP/HTTPS yöntemlerini keşfedebilirsiniz.

Herhangi bir yönteme tıklayabilir ve etrafı keşfedebilirsiniz. POST yöntemine tıklarsanız, bir resim yükleme ve yöntemin parametrelerini güncelleme seçeneği göreceksiniz. 'Yürüt'e basabilirsiniz ve isteğiniz yürütülecektir.

POST isteğinin yanıtını aşağı kaydırarak görebilirsiniz.

Benzer şekilde, verilen diğer yöntemlerle çalışabilir ve ne yaptıklarını görebilirsiniz. Bu, Swagger UI'nin nasıl çalıştığına dair iyi bir fikir verecektir.

Swagger UI'nin yeteneklerinin ötesinde daha sağlam API dokümantasyonu için Apidog'u düşünün. Apidog, tasarım, sahtekarlık, test etme, sürüm oluşturma, işbirliği ve daha fazlası dahil olmak üzere tam API yaşam döngüsü yönetimini sağlar.

CI/CD entegrasyonu ve ekip iş akışları gibi gelişmiş özelliklerle Apidog, API teslimatını kolaylaştırmak için daha eksiksiz bir araç seti sunar. Kapsamlı platformu, API geliştirmeyi ölçeklendirir ve üretkenliği artırır.

Swagger UI Localhost Sorun Giderme

Localhost'ta Swagger UI URL'si ile ilgili sorunlarla karşılaşırsanız, sorunu teşhis etmek ve çözmek için inceleyebileceğiniz çeşitli sorun giderme adımları vardır.

API sunucunuzun çalışır durumda olduğundan emin olun. Sunucunuz çalışmakta sorun yaşıyorsa Swagger UI dokümantasyonu getiremez.
Doğru şekilde ayarlanıp ayarlanmadıklarını görmek için Swagger yapılandırmalarınızı kontrol edin.
Doğru uç noktalarla doğru Swagger UI URL'sini kullanın.
Tarayıcınızın önbelleğini temizleyin. Bazen, önbelleğe alınmış verilerle beklenmedik hatalar oluşabilir.
Herhangi bir değişiklik yaptıktan sonra hem API sunucunuzu hem de tarayıcınızı yeniden başlatın.
Swagger UI'ye erişmek için kullandığınız URL biçimini iki kez kontrol edin.

Sonuç

Sonuç olarak, Swagger UI, kapsamlı API yönetimi teknikleri nedeniyle geliştiriciler arasında hızla popülerlik kazanmaktadır. İyi yapılandırılmış dokümantasyon ve kullanıcı dostu bir arayüz sağlar. Kullanıcılar ayrıca canlı API testi yaparken veri modellerini görselleştirebilir, bu da onu API testi ve hata ayıklama için iyi bir seçim haline getirir.

Swagger UI'nin avantajları olsa da, API'leri test ederken kullanıcının görebileceği çeşitli sınırlamalar da vardır. Geliştiriciler arasında sınırlı işbirliği sağlar ve diğer API yönetim araçlarıyla entegrasyonu desteklemez.