Springboot整合Swagger2以及常用注解说明

引入pom.xml依赖

<!-- swagger2 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>

配置

在config包下面创建Swagger2Config类

@Configuration
@EnableSwagger2
public class Swagger2 {

   

    // 配置Swagger核心配置 docket
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) //指定Api类型为Swagger2
                .apiInfo(apiInfo())                     //用于定义api文档的汇总信息
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.xxxx.controller")) //指定controller包
                .paths(PathSelectors.any())  //所有controller
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("XXXXX平台接口api") //文档页标题
                .contact(new Contact("联系人",
                        "http://rouji4.top",
                        "552004519@qq.com")) //联系人信息
                .description("专为XXXXX提供的API文档") //详细信息
                .version("1.0.1") //版本信息
                .termsOfServiceUrl("http://rouji4.top") //网站信息
                .build();
    }
}

文档访问地址

两种不同的展示风格

注解

@ApiIgnore 忽略某个类下的接口，让其不在文档中展示

@ApiIgnore
@RestController
public class HelloController {

    final static Logger logger= LoggerFactory.getLogger(HelloController.class);

    @GetMapping("hello")
    public Object Hello(){
        logger.info("info:hello!");
        return "hello world";
    }
}

@Api 描述对该控制类所包含的功能

@Api(value = "注册登陆", tags = {"用于注册登陆的相关接口"})
@RestController
@RequestMapping("passport")
public class PassportController extends BaseController {}

@ApiOperation 对某个接口的描述

@ApiOperation(value = "用户注册", notes = "用户注册", httpMethod = "POST")
    @PostMapping("regist")
    public IMOOCJSONResult regist(@RequestBody UserBO userBO,
                                  HttpServletRequest request,
                                  HttpServletResponse response) {}

@ApiModel 可用于对请求实体的描述

ApiModel(value = "用户对象BO",description = "从客户端，用户传入的数据封装在此entity中")
public class UserBO {

    @ApiModelProperty(value = "用户名",name = "username",example = "imooc",required = true)
    private String username;
    @ApiModelProperty(value = "密码",name = "password",example = "123456",required = true)
    private String password;
    @ApiModelProperty(value = "确认密码",name = "confirmPassword",example = "123456",required = false)
    private String confirmPassword;

......略
}