Crear swagger-ui a partir de open-api.yml

29 Jul, 2023 Programación 0

Estoy intentando generar interfaces a partir de una especificación de Open-API y tengo un complemento de Gradle:

implementation(
    "org.springdoc:springdoc-openapi-ui:1.5.12",
    "org.openapitools:openapi-generator-gradle-plugin:5.3.0"
)

Defino el archivo de API como:

def apiFile = "$rootDir/src/main/resources/openapi/api.yml"

La tarea buildOpenApi se configura de la siguiente manera:

task buildOpenApi(type: GenerateTask) {
    generatorName = "spring"
    inputSpec = apiFile
    outputDir = "$buildDir/generated"
    groupId = "$project.group"
    id = "$project.name-java-client"
    version = "$project.version"
    apiPackage = "com.example.my.api"
    modelPackage = "com.example.my.model"
    configOptions = [
            interfaceOnly: "true",
            openApiNullable: "false",
            skipDefaultInterface: "true"
    ]
    globalProperties = [
            apis: "",
            models: ""
    ]
    enablePostProcessFile = true
    skipOverwrite = false
}

La dependencia compileJava se basa en buildOpenApi:

compileJava.dependsOn(buildOpenApi)
sourceSets.main.java.srcDirs = ['build/generated/src','src/main/java']

Tengo un archivo api.yml ubicado en src/main/resources/openapi/api.yml. Cuando ejecuto ./gradlew clean compileJava, se generan las interfaces correctas en el directorio de compilación, por lo que puedo implementarlas. Pero cuando inicio mi aplicación y voy a http://localhost:8080/swagger-ui.html`, veo que Swagger se genera automáticamente a partir de mis clases de controlador, pero no desde el archivoapi.yml`, es decir, no tiene descripciones, ejemplos, etc.

¿Cómo puedo hacer que Swagger se construya a partir de mi archivo api.yml y no desde el código fuente del controlador?

davy.ai

July 29, 2023 at 4:45 am

Para generar Swagger a partir de su archivo api.yml, necesita agregar cierta configuración a su aplicación Spring.

En primer lugar, debe tener la dependencia swagger-ui en su proyecto. Puede agregar esto a su archivo gradle:

implementation "org.springdoc:springdoc-openapi-ui:1.5.12"

Luego, debe configurar su aplicación Spring para generar la documentación de Swagger a partir de su archivo api.yml. Puede hacerlo agregando la anotación @EnableSwagger2 o @EnableSwagger2WebMvc a su clase de configuración de Spring.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }
}

Esta clase de configuración generará la documentación de Swagger a partir de las clases controladoras. Para generar la documentación a partir de su archivo api.yml, debe modificar la configuración de la siguiente manera:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new OpenAPI()
            .components(new Components())
            .info(new Info().title("Título de su API").version("1.0.0"))
            .externalDocs(new ExternalDocumentation()
                .description("Documentación de su API")
                .url("http://localhost:8080/swagger-ui.html"))
            .openapi(convertYamlToJson())
            .extensions(Collections.singletonList(new OpenApiExtension() {
                @Override
                public void apply(OpenAPI openAPI) {
                    SwaggerParseResult swaggerParseResult = new OpenAPIParser().readLocation(
                        "classpath:/ruta/a/su/api.yml", Collections.emptyList(), new ParseOptions());
                    SwaggerConversionResult result = new OpenApiConverter().convert(swaggerParseResult.getOpenAPI());
                    openAPI.setPaths(result.getOpenAPI().getPaths());
                }

                @Override
                public boolean supports(DocumentationType documentationType) {
                    return true;
                }
            }));
    }

    private String convertYamlToJson() {
        try {
            Yaml yaml = new Yaml();
            Map<string, object=""> yamlMap = yaml.load(new FileInputStream("src/main/resources/openapi/api.yml"));
            JSONObject json = new JSONObject(yamlMap);
            return json.toString();
        } catch (FileNotFoundException e) {
            throw new RuntimeException(e.getMessage());
        }
    }
}

Esta configuración analizará el archivo api.yml y lo convertirá del formato YAML al formato JSON. Luego, utilizará el JSON convertido para construir el objeto OpenAPI, que se utilizará para generar la documentación de Swagger.

Una vez que agregue esta configuración a su aplicación Spring, puede iniciar su aplicación e ir a http://localhost:8080/swagger-ui.html` para ver la documentación de Swagger generada a partir de su archivoapi.yml`.</string,>

es.davy.ai

¿Tienes una pregunta?

Crear swagger-ui a partir de open-api.yml

Answer

davy.ai