使用swagger文档

Spring Boot 框架是目前非常流行的微服务框架，我们很多情况下使用它来提供 Rest API，而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档,可以在交互页面测试接口,但是我真没有觉得好用,但是现在都在说,所以集成了一下.

pom.xml中添加依赖

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

添加一个配置类

@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport{

    @Bean
    public Docket api() {
        //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("Authorization").description("登录token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改为自己的包路径
                .apis(RequestHandlerSelectors.basePackage("com.jovision.sfwl"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger接入")
                .version("1.0")
                .build();
    }
// 静态资源放开 否则404
 @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/");
    }
}

上面静态资源也可以用yml/properties配置也可以

spring:
  resources:
    static-locations: classpath:templates/,classpath:static/,classpath:META-INF

这样 swagger就集成完了,接下来是使用,已经扫描到了所有的控制器,那么只需要在控制器的每个请求上加注解就可以了

/**
     * @Description 区域-点位树状查询
     * @Author 寂寞旅行
     * @Date 11:07 2020/8/19
     * @Param [entity]
     * @return com.jovision.sfwl.common.utils.JsonResult
     **/
    @RequestMapping("/areaPointTreeList")
    @ApiOperation(value="获取点位树状查询列表", notes="区域点位树")
    @ApiImplicitParam(name = "", value = "空", required = true, dataType = "String")
    public JsonResult areaPointTreeList() {
        return deviceAreaPointService.areaPointTreeList();
    }

看下效果
访问本地项目+端口+swagger-ui.html 完整路径为http://localhost:9031/swagger-ui.html

image.png

找到刚刚加了注解的控制器的方法

此为改接口加了 文字描述的样子,且红框处,可以直接测试该接口

错误记录:

当出现页面swagger上提示入参无法解析出来,无法显示具体的标注的注释的时候,应该是模型注解上的内容中有 斜杠 / 导致的;将这个斜杠 去掉就好了;

没错,把这个斜杠 / 删除了 就好了 

如果想将swagger 文档导出为word

1. 在swagger界面,点击查看json,然后将json存储一个文档
2.  打开转换网址 swagger转word
3. 在网址中上传json文件,即可生成word了