swagger使用

最近项目中用到了swagger来进行API展示网上搜索了一些文章，为了方便以后使用记录下来

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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
 * @Author lizhongde
 * @Date 2019/3/11
 * @Version V1.0.0
 * @Update 更新说明
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        /*List<Parameter> pars = new ArrayList<Parameter>();
        ParameterBuilder token = new ParameterBuilder();
        ParameterBuilder appKey = new ParameterBuilder();
        ParameterBuilder timeStamp = new ParameterBuilder();
        ParameterBuilder buildNumber = new ParameterBuilder();
        ParameterBuilder version = new ParameterBuilder();
        ParameterBuilder userId = new ParameterBuilder();
        token.name("Token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        appKey.name("App_Key").description("App_Key").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        timeStamp.name("Time_Stamp").description("Time_Stamp").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        buildNumber.name("Build_Number").description("Build_Number").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        version.name("version").description("version").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        userId.name("user_id").description("user_id").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(token.build());
        pars.add(appKey.build());
        pars.add(timeStamp.build());
        pars.add(buildNumber.build());
        pars.add(version.build());
        pars.add(userId.build());*/
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.globalOperationParameters(pars)//设置header头信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.xxx.gateway.h5.controller"))//设置扫描的包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("H5 swagger Api")//设置标题
                .description("这是H5 swagger") //设置描述
                .version("1.0.0")//设置版本
                .build();
    }

}

代码中有一些代码是注释掉的，因为做的的时候拦截器会对请求进行拦截验证，所以需要在header头信息中添加一些内容，注释的代码就是在swagger页面中展示出header信息。

上面是swagger的配置类，在使用是也要对pox.xml进行添加，具体版本

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

添加完成后可以在启动类中添加@EnableSwagger2注解不然会报错，具体的swagger注解意思

- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
 

展示效果为

展示的效果为没有header头信息的效果，如果需要header将注释的代码放开即可。