如何在springboot中集成swagger2

在最近的新项目开发中，深感编写接口文档的低效，维护困难。文档需要更新的时候，需要再次发送一份给前端和别的服务调用方，经常出现文档更新交流不及时的情况，最后果断放弃文档编写，使用招摇，实时生成在线文档，这里集成的是swagger2

我们项目采用的是springboot，所以本文介绍的是在springboot中集成swagger2

1. pom.xml中引入的jar包支持，阿里巴巴私服有该JAR包

        
			io.springfox
			springfox-swagger2
			2.6.1
		

		
			io.springfox
			springfox-swagger-ui
			2.6.1
		

2，新建swggerconfig类，直接建在springboot项目中

package com.crb.init;


import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @Description: swagger配置类
 * @author congc.qiu
 * @date 2018/12/6 18:27
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {

        ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();
        ticketPar.name("Authorization").description("请求头")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).defaultValue("Bearer").build();
        pars.add(ticketPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这里采用包含注解的方式来确定要显示的接口
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //这里采用包扫描的方式来确定要显示的接口
                //.apis(RequestHandlerSelectors.basePackage("com.stylefeng.guns.modular.system.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX Doc")
                .description("XXXApi文档")
                .termsOfServiceUrl("congc.qiu")
                .version("1.0")
                .build();
    }
}

 3，在springboot启动类中加入访问招摇页面的权限（仅限于测试开发阶段使用，上生产需去掉）

/**
 * @Description: 打开访问swagger的权限，生产环境上线后，将此段代码屏蔽即可
 * @author congc.qiu
 * @date 2018/12/6 17:57
 */
    @Configuration
    public class WebMvcConfig extends WebMvcConfigurerAdapter {
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

 4，在项目中加入注解。

 

这样swagger2与springboot就集成完毕了。

当然，还可以在接口输入输出参数上添加描述，可以更方便接口调用方的开发人员阅读配置如下图：

5，启动项目，访问http://localhost:8080/swagger-ui.html即可访问招摇主页就可以看到具体的接口了。

 

 在swagger2还可以进行接口测试，直接填写输入参数，请求接口

招摇注解

• @Api：修饰整个类，描述控制器的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个​​字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数