关于swagger-ui的使用详细过程

• • • • • 1）编写配置文件
        • 2）指定静态文件地址
        • 3）放开swagger页面相关请求资源
        • 4）关于API文档注解
        • 5) swagger导出离线文档

1）编写配置文件

导入jar包

<!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

编写SwaggerConfig配置文件

package com.stu.stusystem.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: cxt
 * @time: 2021/1/22
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径,控制器类包
                .apis(RequestHandlerSelectors.basePackage("com.stu.stusystem.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("管理系统API接口文档")
                //创建人
                .contact(new Contact("cxt", "http://localhost", "10******34@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("系统API描述")
                .build();
    }
}

2）指定静态文件地址

在swagger文件生成后需要指定下文件存放的地方。

/**
 * @author cxt
 * @date 2020/9/9
 * 设置静态文件地址
 */
@Component
public class WebConfigImpl implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
    }
}

3）放开swagger页面相关请求资源

比如shiro中需要设置这几项

        filterChainDefinitionMap.put("/v2/api-docs/**", "anon");
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/webjars/springfox-swagger-ui/**", "anon");

4）关于API文档注解

放在Controller方法上面注解

// tags 表示分组，页面中的接口进行分组

@ApiOperation(value="接口名称" ，notes="接口说明", tags="接口属于哪个分组", httpMethod="接口请求方式")
// 参数说明
@ApiImplicitParams({
    @ApiImplicitParam(name="参数一", value="对参数的说明", required=true [是否必须], dataType="String")
    ……
})
// 请求成功响应格式
@ApiRespones({
    @ApiResponse(code=200, message="请求成功", response=AjaxResponse.class)    
})

放在Bean上面

@ApiModel(value = "这个Bean的说明")
@ApiModelProperty(value = "这个属性的说明", example="1,2,3") // example 中的值表示这个属性都可以返回那些值

5) swagger导出离线文档

Swagger文档  -> Asciidoc文档-> Html/pdf 文档
​             -> Markdown文档

1）导入需要的jar包

<!-- swagger 导出需要的jar-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

2）编写测试类

需要在pom文件中添加Test测试类的jar支持

	  <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

/**
 * @author: cxt
 * @time: 2021/2/3
 */
@ExtendWith(SpringExtension.class)
//@RunWith(SpringRunner.class)   // Junit4 开发者使用这个注解
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class ImportSwagger {
    @Test
    public void generateAsciiDocs() throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN) // 设置生成格式Markdown
                .withOutputLanguage(Language.ZH) // 设置语言中文
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        Swagger2MarkupConverter.from(new URL("http://127.0.0.1:2020/v2/api-docs")) // 复制到浏览器中可以看到JSION数据的地址
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/main/resources/docs"));  // 这里注意，src前面不能有 “/”
    }
}

结果：导出成功的Markdown文档