Swagger 文档在编辑器中显示“语义错误”

问题描述

在为 swagger doc 创建生成 swagger-yaml 文件并使用 editor.swagger.io 后，我收到如下语义错误。到目前为止，我对以下标签错误一无所知：

    Semantic error at paths./v1/entitlement/{entitlementId}.put.parameters.5.schema.$ref
    $ref values must be RFC3986-compliant percent-encoded URIs
    Jump to line 391
    Semantic error at paths./v1/entitlements/{skuId}.post.parameters.4.schema.$ref
    $ref values must be RFC3986-compliant percent-encoded URIs
    Jump to line 700
    Semantic error at paths./v1/entitlements/{skuId}.post.responses.200.schema.$ref
    $ref values must be RFC3986-compliant percent-encoded URIs
    Jump to line 710
    

代码：

SwaggerConfig.java - 为相应的应用程序控制器配置 swagger2 属性。

package com.pearson.gsam.product.management.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.spi.DocumentationType.SWAGGER_2;

@Configuration
@EnableSwagger2
@Profile({ "dev","qa","local","stg","it" })
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Value("${application.name}")
    String appName;
    @Value("${application.description}")
    String appDescription;
    @Value("${application.version}")
    private String appVersion;

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


    private ApiInfo apiEndPointsInfo() {
        return new ApiInfoBuilder()
                .title(appName)
                .description(appDescription)
                .version(appVersion)
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/meta-inf/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/meta-inf/resources/webjars/");

    }
}

    

SwaggerDoc.java - 用于创建 swagger-API.YAML 文件并存储在特定目录中

    package docs;
    
    import static org.springframework.test.web.servlet.request.mockmvcRequestBuilders.get;
    import static org.springframework.test.web.servlet.result.mockmvcResultHandlers.print;
    import static org.springframework.test.web.servlet.result.mockmvcResultMatchers.status;
    
    import java.io.File;
    import java.io.FileWriter;
    import java.io.Writer;
    
    import com.pearson.gsam.product.management.entitlement.service.ProductManagementEntitlementService;
    import com.pearson.gsam.product.management.entitlement.service.ProductManagementEntitlementServiceImpl;
    import com.pearson.gsam.product.management.kafka.EventService;
    import com.pearson.gsam.product.management.kafka.KafkaCallBackHandler;
    import org.apache.commons.io.IoUtils;
    import org.junit.jupiter.api.Test;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
    import org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration;
    import org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration;
    import org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongoAutoConfiguration;
    import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfiguremockmvc;
    import org.springframework.boot.test.context.SpringBoottest;
    import org.springframework.boot.test.mock.mockito.MockBean;
    import org.springframework.boot.test.mock.mockito.MockBeans;
    import org.springframework.context.annotation.ComponentScan;
    import org.springframework.context.annotation.Import;
    import org.springframework.kafka.test.context.EmbeddedKafka;
    import org.springframework.test.annotation.DirtiesContext;
    import org.springframework.test.context.ActiveProfiles;
    import org.springframework.test.web.servlet.mockmvc;
    
    import com.fasterxml.jackson.databind.JsonNode;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
    import com.pearson.gsam.product.management.config.SwaggerConfig;
    import com.pearson.gsam.product.management.entitlement.ProductManagementEntitlementApplication ;
    
    @ActiveProfiles( "it" )
    @DirtiesContext
    @SpringBoottest(classes = {SwaggerConfig.class},properties = {"spring.profiles.active=it"})
    //@SpringBoottest(classes = ProductManagementEntitlementApplication.class)
    @EnableAutoConfiguration(exclude = {EmbeddedMongoAutoConfiguration.class,MongoAutoConfiguration.class,KafkaAutoConfiguration.class})
    @AutoConfiguremockmvc
    @ComponentScan(basePackages = {"com.pearson.gsam.product.management.controller","springfox"})
    //@EmbeddedKafka
    @MockBeans(
            @MockBean( classes = { ProductManagementEntitlementService.class,EventService.class
                    })
    )
    @Import(SwaggerConfig.class)
    public class SwaggerDoc {
        @Value("${service-name}")
        String serviceName;
        
        @Autowired
        private mockmvc mockmvc;
    
        @Test
        public void generateSwagggerDoc() throws Exception {
            String contentAsstring = mockmvc.perform(get("/v2/api-docs"))
                    .andDo(print())
                    .andExpect(status().isOk())
                    .andReturn()
                    .getResponse().getContentAsstring();
    
            // parse JSON
            JsonNode jsonNodeTree = new ObjectMapper().readTree(contentAsstring);
            // save it as YAML
            String jsonAsYaml = new YAMLMapper().writeValueAsstring(jsonNodeTree);
    
            File file = new File("swagger/"+serviceName+"-API_Swagger.yml");
            file.getParentFile().mkdirs();
    
            try (Writer writer = new FileWriter(file)) {
                IoUtils.write(jsonAsYaml,writer);
            }
        }
    }
    
    

我正在使用以下 jars 进行 swagger：

    compile group: 'io.springfox',name: 'springfox-swagger2',version: '2.9.2'
        compile group: 'io.springfox',name: 'springfox-swagger-ui',version: '2.10.0'

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）