giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

Quality

90%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

This version of the tile failed moderation

Moderation pipeline encountered an internal error

Build Integration

Name: giuseppe-trisciuoglio/developer-kit
Rating: 90.85333333333334 (1 reviews)
Author: giuseppe-trisciuoglio

Maven Plugin

OpenAPI Generation Plugin

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
    </configuration>
</plugin>

Custom Configuration

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.yaml</outputFileName>
        <outputDir>${project.build.directory}/docs</outputDir>
        <skip>false</skip>
        <headers>
            <Authorization>Bearer test-token</Authorization>
        </headers>
    </configuration>
</plugin>

Multiple API Groups

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>generate-public-api</id>
            <phase>verify</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs/public</apiDocsUrl>
                <outputFileName>public-api.json</outputFileName>
                <outputDir>${project.build.directory}/docs</outputDir>
            </configuration>
        </execution>
        <execution>
            <id>generate-admin-api</id>
            <phase>verify</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs/admin</apiDocsUrl>
                <outputFileName>admin-api.json</outputFileName>
                <outputDir>${project.build.directory}/docs</outputDir>
            </configuration>
        </execution>
    </executions>
</plugin>

Gradle Plugin

Basic Gradle Configuration

plugins {
    id 'org.springdoc.openapi-gradle-plugin' version '1.9.0'
}

openApi {
    apiDocsUrl = "http://localhost:8080/v3/api-docs"
    outputDir = file("$buildDir/docs")
    outputFileName = "openapi.json"
}

Custom Gradle Configuration

openapi {
    apiDocsUrl.set("http://localhost:8080/v3/api-docs")
    outputDir.set(file("$buildDir/docs"))
    outputFileName.set("openapi.yaml")
    groupedApiMappings.set([
        "public": "http://localhost:8080/v3/api-docs/public",
        "admin": "http://localhost:8080/v3/api-docs/admin"
    ])
}

CI/CD Integration

GitHub Actions Workflow

name: Generate API Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Run application
        run: |
          mvn spring-boot:run &
          sleep 30  # Wait for app to start

      - name: Generate OpenAPI docs
        run: mvn verify

      - name: Upload API docs
        uses: actions/upload-artifact@v3
        with:
          name: openapi-spec
          path: target/openapi.json

GitLab CI Pipeline

stages:
  - build
  - docs

build:
  stage: build
  script:
    - mvn clean install
  artifacts:
    paths:
      - target/*.jar

generate-docs:
  stage: docs
  services:
    - name: app:latest
      alias: api
  script:
    - apk add --no-cache curl
    - curl http://api:8080/v3/api-docs -o openapi.json
  artifacts:
    paths:
      - openapi.json
  only:
    - main

Automated Testing

OpenAPI Specification Validation

import org.springdoc.core.utils.SpringDocUtils;
import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest
class OpenApiDocumentationTest {

    @Autowired
    private OpenApiContract openApiContract;

    @Test
    void validateOpenApiSpec() {
        OpenAPI openAPI = openApiContract.getOpenApi();

        assertNotNull(openAPI);
        assertNotNull(openAPI.getInfo());
        assertEquals("1.0.0", openAPI.getInfo().getVersion());
        assertFalse(openAPI.getPaths().isEmpty());
    }

    @Test
    void allPathsHaveDocumentation() {
        OpenAPI openAPI = openApiContract.getOpenApi();

        openAPI.getPaths().forEach((path, pathItem) -> {
            pathItem.readOperationsMap().forEach((method, operation) -> {
                assertNotNull(operation.getSummary(), "Missing summary for " + method + " " + path);
                assertFalse(operation.getResponses().isEmpty(), "No responses for " + method + " " + path);
            });
        });
    }
}

Schema Validation Tests

@Test
void validateBookSchema() {
    OpenAPI openAPI = openApiContract.getOpenApi();
    Schema bookSchema = openAPI.getComponents().getSchemas().get("Book");

    assertNotNull(bookSchema);
    assertTrue(bookSchema.getProperties().containsKey("id"));
    assertTrue(bookSchema.getProperties().containsKey("title"));
    assertTrue(bookSchema.getProperties().containsKey("author"));
}

Static Documentation Generation

Generate Swagger UI Static Files

# Using Maven
mvn verify

# Using Gradle
gradle openApi

# The generated files will be in:
# - target/openapi.json (Maven)
# - buildDir/docs/openapi.json (Gradle)

Custom Output Directory

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <configuration>
        <outputDir>${project.basedir}/src/main/resources/static/docs</outputDir>
        <outputFileName>swagger.json</outputFileName>
    </configuration>
</plugin>

Redoc Integration

Add Redoc Dependency

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

Access Redoc UI

After adding the dependency:

Redoc UI: http://localhost:8080/api-docs (Redoc styling)
Swagger UI: http://localhost:8080/swagger-ui/index.html (original)

Custom Redoc Configuration

@Bean
public OpenAPI openAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("API Documentation")
            .version("1.0.0")
        );
}

@Configuration
public class RedocConfig {

    @Bean
    public IndexPageCustomizer indexPageCustomizer() {
        return indexHtml -> indexHtml.replace(
            "<title>",
            "<link rel='stylesheet' href='/webjars/redoc/redoc.css'><script src='/webjars/redoc/redoc.standalone.js'></script><title>"
        );
    }
}

Version Management

API Versioning Strategy

# application.yml
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

# Multiple API versions
springdoc:
  group-configs:
    - group: 'v1'
      paths-to-match: /api/v1/**
    - group: 'v2'
      paths-to-match: /api/v2/**

Generate Versioned Specs

# Generate v1 spec
curl http://localhost:8080/v3/api-docs/v1 > openapi-v1.json

# Generate v2 spec
curl http://localhost:8080/v3/api-docs/v2 > openapi-v2.json