SpringMVC注解配置Swagger2步骤及相关知识点

淡淡的烟草味﹌ 2022-06-16 02:48 367阅读 0赞

Swagger2的功能不多说了，百度一下随处可见，配置步骤也十分简单，但一些点百度到的很多都不太详细，个人进行了一些补充

1、pom.xml添加swagger2依赖（个人一般直接到http://search.maven.org/搜索artifactid点最新版本copy到pom里）

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

2、添加设置swagger2配置类

package pers.graduation.config;
    
    import com.google.common.collect.Sets;
    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.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * Created by Wilson on 2017/5/2.
     */
    @Configuration
    @EnableSwagger2
    @EnableWebMvc
    @ComponentScan(basePackages = "pers.graduation.controller")
    public class SwaggerConfig extends WebMvcConfigurationSupport {
        @Bean
        public Docket commonDocket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("通用API接口文档")
                    .apiInfo(apiInfo("提供通用接口"))
                    .pathMapping("/")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.common"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        @Bean
        public Docket normalUserDocket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("普通用户API文档")
                    .apiInfo(apiInfo("提供普通用户接口"))
                    .protocols(Sets.newHashSet("https","http"))
                    .produces(Sets.newHashSet("html/text"))
                    .pathMapping("/")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.candidate"))//设置生成的Docket对应的Controller为candidate下的所有Controller
                    .paths(PathSelectors.any())
                    .build();
        }
    
        @Bean
        public Docket companyUserDocket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("企业用户API接口文档")
                    .apiInfo(apiInfo("提供企业用户接口"))
                    .pathMapping("/")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.company"))
                    .paths(PathSelectors.any())
                    .build();
        }
     //设置文档信息
        private ApiInfo apiInfo(String desc) {
            return new ApiInfo(
                    "Test Website", //标题名称
                    desc, //文档描述
                    "1.0.1", //版本号，自定义
                    "http://blog.csdn.net/z28126308", //许可人URL
                    contact(), //联系方式实体类
                    "Wilson", //许可人，许可证
                    "http://blog.csdn.net/z28126308"); //许可URL
        }
     //设置联系方式
        private Contact contact() {
            return new Contact("Wilson", "http://blog.csdn.net/z28126308", "z28126308@163.com");
        }
    }

Docket类的方法：

Docket groupName(String var):设置栏目名

Docket apiInfo(ApiInfo apiInfo):设置文档信息

Docket pathMapping(String path):设置api根路径

Docket protocols(Set<String> protocols):设置协议，Sets为com.goolge.common下的类，Sets.newHashSet("https","http")相当于new HashSet()\{ \{add("https");add("http");\}\};

ApiSelectorBuilder select():初始化并返回一个API选择构造器

ApiSelectorBuilder类的方法：

ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象

ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选，该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与

RequestHandlerSelectors类的方法：

Predicate<RequestHandler> any()：返回包含所有满足条件的请求处理器的断言，该断言总为true

Predicate<RequestHandler> none()：返回不满足条件的请求处理器的断言,该断言总为false

Predicate<RequestHandler> basePackage(final String basePackage)：返回一个断言(Predicate)，该断言包含所有匹配basePackage下所有类的请求路径的请求处理器

PathSelectors类的方法：

Predicate<String> any():满足条件的路径，该断言总为true

Predicate<String> none():不满足条件的路径,该断言总为false

Predicate<String> regex(final String pathRegex):符合正则的路径

不讲太多，有兴趣的去看源码

3、设置swagger-ui.html默认路径，servlet的配置文件添加

<mvc:annotation-driven></mvc:annotation-driven>  
<mvc:resources mapping="/webjars/\*\*" location="classpath:/META-INF/resources/webjars"/>

swagger-ui.html位于springfox-swagger-ui jar包中的META-INF/resources/目录下，项目编译后swagger-ui.html将添加到classpath的/META-INF/resources/下，所以添加mapping="/webjars/\*\*" 可通过localhost:端口号/项目名/swagger-ui.html打开SwaggerUI

4、常用注解

Swagger所有注解并非必须，若不加就只显示类目/方法名/参数名没有注释而已，但若注解中含@ApiParam不对应@RequestParam将无效果

@Api:注解controller，value为@RequestMapping路径

@ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false

@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名，value为注释，defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须，默认为false

@ApiModel:注解Model

@ApiModelProperty:注解Model下的属性，当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value

@ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示

效果图（若要传送对象作为参数，只需添加@ModelAttribute或@RequestBody）：![Center][]

传送对象参数：

model:

private String telephone;
    
    @Column
    private String email;
    
    @Column
    private Long companyId;
    
    @Transient
    private ComCompany comCompany;
    
    @Transient
    private List<PositionWelfare> welfareList;

Controller方法:

@ResponseBody
    @RequestMapping(value = "/per-addPosition", method = RequestMethod.POST)
    @ApiOperation(value = "添加职位")
    public Object addPosition(@ModelAttribute ComPosition position, @RequestParam String[] welfareName) {

Swagger

![Center 1][]

[Center]: /images/20220616/18ca51d27fef4ac9b3a103e8cf230c81.png
[Center 1]: /images/20220616/2975d86a06674e06bd64f7bed05ff8d9.png