springBoot中swagger 的使用

时间 2021-01-09 标签 swagger springBoot 前后端分离

springBoot中swagger 的使用以及常见注解的总结

一，在pom.xml 中添加依赖

<!-- ======================swagger 支持============================-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${swagger.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${swagger.version}</version>
		</dependency>
<!--================================================================-->

${swagger.version} 可以在中声明版本

<properties>
		<java.version>1.8</java.version>
		<swagger.version>2.7.0</swagger.version>
	</properties>

二，创建配置类

在启动类同级或者子级目录创建java文件文件位置很重要如果文件在启动类的父级目录在启动项目之后在浏览器中是打不开 swagger-ui 的。（之前眼花放错了位置解决了半天才发现这个问题）
开始创建配置类

package com.learn.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/** * @Auther: Administrator * @Date: 2019/3/11 * @Description: */
@Configuration
@EnableSwagger2//这两个注解是必须出现在配置类中
public class Swagger2 {

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.learn.control"))//指定扫描api的位置
            .paths(PathSelectors.any())//对所有api监控
            .paths(Predicates.not(PathSelectors.regex("/error.*")))//选择忽略的路径
            .build();
}

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }
}

这样就是一个简单的配置类就完成了。接下来就是在controller 中使用了。

三，controller 中使用swagger 注解

package com.learn.control;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/students")
@Api(tags = "SayController|一个用来测试swagger注解的控制器")
public class Cont {

    @ApiOperation(value="获取用户详细信息")
    @ApiImplicitParam(name = "mes", value = "介绍", required = true, paramType = "query" ,dataType = "java.lang.String")
    @GetMapping(value="test")
    public Object getUser(@RequestParam(name = "mes", required = true) String mes) {
        System.out.println(mes);
        return mes;
    }
}

现在启动项目访问http://127.0.0.1:8080/swagger-ui.html#这个链接就可以看到swagger的界面了。

具体对比可以参考之前的配置。大多是注解都能通过效果图看出来作用，这里再说一下 @GetMapping(value=“test”)和@ApiImplicitParam( required = true )这两个注解。

@GetMapping(value=“test”) 是springBoot 中的注解相当于@RequestMapping (method = RequestMethod .GET )如果直接采用RequestMapping 而且不指明method类型在swagger-ui 界面则会出现多个菜单，post、get等。所以为了避免忘记写method 所以建议用 @GetMapping @PostMapping这种方式。

@ApiImplicitParam( required = true ) true 是字段必填反之不做限制。

springBoot中swagger 的使用