SpringMvc swagger2配置及使用

最新推荐文章于 2024-07-30 17:38:36 发布

竹浆

最新推荐文章于 2024-07-30 17:38:36 发布

阅读量707

点赞数

文章标签： java

本文链接：https://blog.csdn.net/qq_16258769/article/details/104813728

版权

配置：

引入jar包（由于先使用2.7.0导致类的说明无法显示具体问题有待大家一起探讨，现改为使用2.6.0版本，）

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

引入spring java配置

package com.ak1ak1.config;

import com.google.common.base.Predicate;
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 org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.base.Predicates.or;
import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration    // 配置注解，自动在本类上下文加载一些环境变量信息
@EnableSwagger2   // 使swagger2生效
@EnableWebMvc
//@ComponentScan(basePackages = {"com.ak1ak1.controller.v1"})  //需要扫描的包路径
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("APi文档")
                .select()   // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage("com.ak1ak1.controller.v1"))//需要扫描的包路径
                .paths(paths())
                //.apis(RequestHandlerSelectors.any())  // 对所有api进行监控
                //.paths(PathSelectors.any())   // 对所有路径进行监控
                .build()
              //  .securitySchemes(securitySchemes())
              //  .securityContexts(securityContexts())
                ;
    }

    private Predicate<String> paths() {
    	return PathSelectors.any();
        //return or(regex("/person.*"));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APi文档")
                .description("此APi文档接口调用")
                //.license("License Version 2.0")
                //.licenseUrl("http://blog.csdn.net/yangshijin1988")
                .version("2.0").build();
    }
    
//--------------------------------------------------------------------------------------------------------------------------------------------    
    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("clientId", "客户端ID", "header"),
                new ApiKey("clientSecret", "客户端秘钥", "header"),
                new ApiKey("accessToken", "客户端访问标识", "header"));
    }

    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("/*.*"))
                        .build()
        );
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("clientId", authorizationScopes),
                new SecurityReference("clientSecret", authorizationScopes),
                new SecurityReference("accessToken", authorizationScopes));
    }
}

使用

启动项目服务后访问地址: http://127.0.0.1:8084/swagger-ui.html#/（注：服务器地址加项目端口）；
类注解说明：
@Api(description=“广告推荐”, tags={“advertisement”},value=“advertisement”)
2.1：说明（）
tags–表示说明不能填写中文，需要中文请用 description
value–也是说明，可以使用tags替代但是tags如果有多个值，会生成多个lis
2.2案例
Java控制层类

Swagger页面显示情况

方法注解说明: @ApiOperation(httpMethod = “POST”, value = “个人信息”)
3.1说明
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
(注意事项：若方法名开头含add，get，del，up的字眼的情况请给方法设置该方法的请求方式httpMethod)
3.2案例

Swagger页面显示

字段注解说明:
4.1方式1：在方法上添加注解使用

Swagger页面显示

4.2方式二：在方法里：
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

或者

实体类注解说明
@ApiModel()用于类；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏