项目总结60：Springboot集成swagger2

Springboot集成swagger2

一、swagger2简介

　　swagger2是一款开源项目，可以根据配置自动生成项目接口文档。可以规范文档，减少文档撰写时间

二、代码示例

1- 引入依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <!--引入ui包-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>

 

2-配置类

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket webApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("APP端接口")//1-端口所属模块
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.bigdemo.swagger"))//扫描当前package下的controller
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//扫描类上标有@Api的controller类
                .apis(RequestHandlerSelectors.withMethodAnnotation(SwaggerVisibleAnnotation.class))//扫描方法上标有@SwaggerVisibleAnnotation的方法
                .paths(PathSelectors.any())
                .build();
    }


    /*** 获取 API 信息 方法 ***/
    private ApiInfo apiInfo() {
        // 作者 名称 连接地址 邮箱 是 固定写法
        Contact contact = new Contact("TangYj", null, null);
        // 返回一个 构造对象
        return new ApiInfoBuilder()
                .title("fmk项目模版")
                .description("项目接口api文档")
                .contact(contact)
                .version("1.0")
                .build();
    }

}

 

3-Controller

@Api(value = "登陆相关", tags = "登陆相关接口")
@RestController
@RequestMapping(value="/api")
public class SwaggerTestController {

    @ApiOperation("登陆Path")
    @SwaggerVisibleAnnotation
    @PostMapping(value="/login/path/{account}/{password}")
    public LoginRes loginPath(
            @ApiParam(name = "account",value = "账号",required = true)@PathVariable(name = "account",required = true)String account,
            @ApiParam(name = "password",value = "密码",required = true)@PathVariable(name = "password",required = true)String password
    ) throws Exception {
        //省略业务代码......
        System.out.println("account： " + account);
        System.out.println("password： " + password);
        return new LoginRes("tokenPath");
    }



    @ApiOperation("登陆Query")
    @SwaggerVisibleAnnotation
    @PostMapping(value="/login/query")
    public LoginRes loginQuery(
            @ApiParam(name = "account",value = "账号",required = true)@RequestParam(name = "account",required = true)String account, // @ApiParam对参数进行解释
            @ApiParam(name = "password",value = "密码",required = true)@RequestParam(name = "password",required = true)String password
    ) throws Exception {
        //省略业务代码......
        System.out.println("account： " + account);
        System.out.println("password： " + password);
        return new LoginRes("tokenQuery");
    }


    @ApiOperation("登陆POST")//接口名称
    @SwaggerVisibleAnnotation//自定义注解，接口是否再文档中展示，没有该注解表示不展示
    @PostMapping(value="/login/post")
    public LoginRes login(@RequestBody LoginReq loginReq) throws Exception {
        //省略业务代码......
        System.out.println("account： " + loginReq.getAccount());
        System.out.println("password： " + loginReq.getPassword());
        return new LoginRes("tokenPost");
    }
}

 

4-自定义注解

/**
 * 用于swagger自定义可见注解
 *
 * @author cjm
 * @date 2019/10/11 13:36
 **/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerVisibleAnnotation {

}

 

5-接口请求和返回实体类

@ApiModel("登陆请求参数")//类名称描述
@Data
@AllArgsConstructor
@NoArgsConstructor
public class LoginReq {

    @ApiModelProperty("账号")//参数描述
    private String account;
    @ApiModelProperty("密码")
    private String password;

}
--------------------------------------------------------------------------------
@ApiModel("登陆返回参数")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class LoginRes {

    @ApiModelProperty("用户令牌")
    private String token;

    
}

 

三、效果展示(网址：http://IP:port/doc.html)

主页展示

 

 具体接口文档页展示

 

具体接口调试页展示

 

END