springboot2.x中利用swagger2生成restfulAPI

1、加入pom依赖

  		<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>

2、基础配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder().title("API接口文档")
                .description("档案管理系统接口文档")
                .version("1.0.0")
                .build();
    }
    @Bean
    public Docket createRestApi() {
    
    
           
		   //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        ParameterBuilder tokenParAppId = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("Authorization")
                .description("令牌(登录后获取令牌)")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();

        tokenParAppId.name("appId")
                .description("令牌(登录后获取AppId)")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());
        pars.add(tokenParAppId.build());
		

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jw.jaf.controller")) //这里写的是API接口所在的包位置
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(productApiInfo());
    }


    private ApiInfo productApiInfo() {
    
    
        return new ApiInfoBuilder()
                        .title("档案管理系统API")
                       .description("物华天宝 , 龙光射牛斗之墟 \r" +
                                        "人杰地灵 , 徐孺下陈蕃之榻")
                        //.termsOfServiceUrl("www.baidu.com")
                        // .contact(new Contact("Q_先生", "www.baidu.com", "邮箱"))
                        .version("1.0")
                        .build();
            }

}

3、swagger-ui.html访问权限类

@Configuration
public class SwaggerSourceConfig extends WebMvcConfigurerAdapter {
    
    

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    
        //*swagger-ui,允许访问swagger接口文档*//*
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }


}	

4、swagger2注解

4.1 实体类属性

public class VideoDto implements Serializable {
    
    
		/**
		 * 主键
		 */
		private String id;

		/**
		 * 年度
		 */
		@ApiModelProperty(value = "年度")
		private String year;

		/**
		 * 档号
		 */
		@ApiModelProperty(value = "档号")
		private String archiveNo;

		/**
		。。。。。

4.2 控制层

@Api(tags = "声像档案控制层")
	@RestController
	@RequestMapping("/v0.1/api/video")
	public class VideoController {
    
    		
		
	}

4.3 控制层中方法

@ApiOperation(value="声像档案列表查询接口 author: zyf",notes ="查询档案列表")
    @ApiImplicitParams({
    
    
           // @ApiImplicitParam(name = "dto", value = "声像档案实体dto", required = true, dataType = "VideoDto"),
            @ApiImplicitParam(name = "$limit", value = "分页大小", required = false, dataType = "Long"),
            @ApiImplicitParam(name = "$offset", value = "起始页", required = false, dataType = "Long")
    })

    /**
     * 列表查询
     * @param limit
     * @param offset
     * @param dto
     * @return
     */
    @PostMapping("/list")
    public PagingResult<VideoDto> getProjects(@RequestParam(required = false, name = "$limit", defaultValue = "10") Integer limit,
                                              @RequestParam(required = false, name = "$offset", defaultValue = "0") Integer offset,
                                              @Valid VideoDto dto){
    
    
        RowBounds rowBounds = new RowBounds(offset, limit);
        return this.videoService.list(dto, rowBounds);
    }
	
	

注：实体外的参数可以用注解 @ApiImplicitParams 说明，如$limit是分页大小

5、访问
http://localhost:8080/swagger-ui.html

注：接口中的Authorization参数为登录后令牌