Kihagyás

Swagger

Swagger s a toolkit designed for describing, documenting, and interactively testing REST APIs based on the OpenAPI specification.

With it you can:

  • describe an API in a standardized way (endpoints, parameters, responses),
  • generate documentation automatically,
  • try API calls directly from the browser.

Swagger

Links

How does it relate to testing?

Interactive API testing:

Swagger UI allows you to:

  • manually try out the endpoints,
  • see responses and status codes,
  • test different inputs.

This acts as a form of manual API testing interface.

Support for test automation:

Based on the Swagger/OpenAPI specification, most modern test frameworks can:

  • generate test data,
  • validate endpoints,
  • even produce test code (Swagger Codegen, OpenAPI Generator).

This speeds up:

  • integration tests,
  • API regression tests,
  • contract-based testing.

The Swagger file (openapi.json / openapi.yaml) is the system’s “contract”. If it changes, it can automatically indicate that:

  • a parameter was modified,
  • the response code changed,
  • a field disappeared.

This way regression issues can be detected during development.

Easy to integrate into CI/CD:

In CI execution, based on the Swagger specification:

  • consistency between code and documentation can be checked,
  • automatic API validation tools can be executed,
  • client libraries can be generated for testing.

Swagger and FastApi

Environment setup:

1
2
3
4
5
mkdir fastapi-swagger-demo
cd fastapi-swagger-demo

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Installing FastAPI + Uvicorn:

1
pip install fastapi "uvicorn[standard]"

Minimal application:

Hozzuk létre az alábbi main.py filet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="Demo API",
    description="Simple FastAPI example with Swagger UI",
    version="1.0.0",
)


class User(BaseModel):
    id: int
    name: str
    email: str


@app.get("/hello", summary="Simple hello endpoint", tags=["Hello"])
def hello():
    """
    Simple test endpoint.

    Returns a fixed string.
    """
    return {"message": "Hello, FastAPI!"}


@app.get("/users/{user_id}", response_model=User, tags=["Users"])
def get_user(user_id: int):
    """
    Query a user by their ID.

    - **user_id**: the user’s identifier
    """
    # Normally data would come from a database
    return User(id=user_id, name="Teszt Elek", email="teszt@example.com")

Run the application

1
uvicorn main:app --reload
  • main → filename (main.py)
  • app → the FastAPI() instance

Open in browser:

You can call endpoints interactively there, pass parameters, inspect responses — this is a classic method of manual API testing.

What is uvicorn?

Uvicorn is a lightweight, high-performance ASGI (Asynchronous Server Gateway Interface) server for Python, designed to run async (async/await) web applications.

What is FastApi?

FastAPI is a Python framework for quickly building high-performance REST APIs based on type annotations, automatically generating Swagger documentation.

Swagger and Java

On the Java side, the most common “classic” solution is:

  • Spring Boot REST API
  • springdoc-openapi-starter-webmvc-ui: provides OpenAPI generation and Swagger UI

Prerequisites:

  • JDK 17 (or newer, but 17 is the standard for Spring Boot 3)
  • Maven (or Gradle — here we use Maven)

*Environment preparation:

1
2
mkdir spring-swagger-demo
cd spring-swagger-demo

Create a Maven project in IntelliJ IDEA:

maven

Use the following POM file:

Place it in the project root.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                         http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<!-- Spring Boot parent: provides versions, plugin config -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.0</version>
    <relativePath/> <!-- disable local lookup -->
</parent>

<groupId>hu.demo</groupId>
<artifactId>spring-swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>spring-swagger-demo</name>
<description>Demo Spring Boot app with Swagger (springdoc-openapi)</description>

<properties>
    <java.version>17</java.version>
</properties>

<dependencies>
    <!-- Spring Web (REST API) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

     <!-- Bean Validation (optional, but useful) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- springdoc-openapi + Swagger UI -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.6.0</version>
    </dependency>

     <!-- Testing (JUnit etc.) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Version inherited from parent -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

</project>

Application entry point: src/main/java/hu/demo/springswaggerdemo/SpringSwaggerDemoApplication.java

Make sure the project structure matches this!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
package hu.demo.springswaggerdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringSwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringSwaggerDemoApplication.class, args);
    }
}

Create a UserController.java file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
package hu.demo.springswaggerdemo;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.List;

// DTO
class User {
    private Long id;
    private String name;
    private String email;

    public User() {}

    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "User management endpoints")

public class UserController {

    @GetMapping
    @Operation(summary = "List users", description = "Query all users.")
    public List<User> listUsers() {
        return List.of(
                new User(1L, "Teszt Elek", "teszt@example.com"),
                new User(2L, "Kiss Anna", "anna@example.com")
        );
    }

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "Someone", "valaki@example.com");
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        // Normally we would save to a database here
        user.setId(100L);
        return user;
    }
}
Utolsó frissítés: 2025-11-30 15:56:17