Swagger - Yash-777/MyWorld GitHub Wiki

Adding Swagger (now known as OpenAPI) to your API helps generate interactive API documentation. The setup process depends on the programming language and framework you're using.

Please let me know your tech stack (e.g., Node.js + Express, Python + Flask, Java + Spring Boot, .NET Core, etc.). But here’s a quick summary of how to add Swagger for the most common stacks:

Java + Spring Boot

✅ 1. Add the Correct Dependency : If you're using Spring Boot 2.x or 3.x, use the right version of springdoc-openapi-ui.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.7.0</version>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

✅ 2. Expose the Swagger UI: After restarting the app, Swagger UI should be available at:

http://localhost:8080/swagger-ui.html
or
http://localhost:8080/swagger-ui/index.html

✅ 3. Sample Controller (Ensure You Have Endpoints) Swagger only shows up if there are REST endpoints defined.

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello World";
    }
}

✅ 4. Optional: Annotate with OpenAPI Info You can add this to your main class or a config class:

@OpenAPIDefinition(
    info = @Info(
        title = "My API",
        version = "1.0",
        description = "My API Documentation"
    )
)
@SpringBootApplication
public class MyApp {
    public static void main(String[] args) {
        SpringApplication.run(MyApp.class, args);
    }
}

✅ 5. Check for Conflicting Web Security (Spring Security Users)

If you have Spring Security configured, you may need to whitelist Swagger paths.

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests()
            .requestMatchers(
                "/swagger-ui/**",
                "/v3/api-docs/**"
            ).permitAll()
            .anyRequest().authenticated()
            .and().httpBasic();

        return http.build();
    }
}