Springboot2.x集成swagger2生成接口文档

Springboot2.x集成swagger2生成接口文档

1. 引入依赖

 <!--集成swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2. 编写Swagger2Config配置类

package com.turing.team_website.configuration;

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;

/**
 * @author Jack
 * @date 2019-07-08-19:05
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("前台访客API文档")
                .apiInfo(apiInfo1())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.turing.team_website.controller.guest"))
                .paths(PathSelectors.any())
                .build();
    }
    @Bean
    public Docket createRestApi2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台管理API文档")
                .apiInfo(apiInfo2())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.turing.team_website.controller.admin"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo1(){
        return new ApiInfoBuilder()
                .title("图灵智能创新网站前台接口文档")
                .version("1.0")
                .build();
    }

    private ApiInfo apiInfo2(){
        return new ApiInfoBuilder()
                .title("图灵智能创新团队网站后台管理接口")
                .version("1.0")
                .build();
    }

}

注解	解释
@EnableSwagger2	开启swagger2
@Configuration	声明配置类
@Bean	注册到Spring容器中

###2.1 Docket(一个Docket对象就是一个大的接口文档)

关键字	解释
groupName	该接口文档的命名, 显示在网页右上方
apiInfo	API的信息, 显示在接口上方
apis(RequestHandlerSelectors.basePackage(controller包的位置))	扫描swagger注解的controller包

3. controller层注解使用

关键字	解释
@Api	标注在类上, 属性tags可指定该接口的名字
@ApiImplicitParam	单个参数, 属性:name(参数名),value(参数解释说明),paramType(参数路径类型),dataType(参数数据类型)…
@ApiImplicitParams	k可指定多个参数,用数组表示, 数组内是一个个@ApiImplicitParam注解

4. controller层使用例子

package com.turing.team_website.controller.guest;

import com.turing.team_website.entity.JsonResult;
import com.turing.team_website.entity.Member;
import com.turing.team_website.service.guest.GuestMemberService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @author Jack
 * @date 2019-07-08-14:39
 */
@Api(tags = "团队成员接口")
@RestController
@RequestMapping("/guest/member")
public class GuestMemberController {

    @Autowired
    GuestMemberService guestMemberService;

    @GetMapping("")
    public JsonResult findAllMembers(){

        List<Member> members = guestMemberService.findAllMembers();
        return JsonResult.success().add("members", members);

    }

    @ApiImplicitParam(name = "technology", value = "技术方向(前端,后台,计算机视觉,自然语言处理)",
            paramType = "query", dataType = "String", required = true)
    @GetMapping("/tech")
    public JsonResult findMembersByTech(@RequestParam(name = "technology") String technology){

        List<Member> members = guestMemberService.findMembersByTech(technology);
        return JsonResult.success().add("members", members);

    }

    @ApiImplicitParam(name = "memberId",value = "成员id" ,paramType = "path", dataType = "Integer", required = true)
    @GetMapping("/{memberId}")
    public JsonResult findMemberById(@PathVariable Integer memberId){

        Member member = guestMemberService.findMemberById(memberId);
        return JsonResult.success().add("member",member);

    }
}

5. 页面展示