springboot整合Swagger-UI实现在线API文档

原创
2020/07/27 15:06
阅读数 116

Swagger-UI是HTML, Javascript, CSS的一个集合,可以动态地根据注解生成在线API文档。

常用注解

  • @Api:用于修饰Controller类,生成Controller相关文档信息
  • @ApiOperation:用于修饰Controller类中的方法,生成接口方法相关文档信息
  • @ApiParam:用于修饰接口中的参数,生成接口参数相关文档信息
  • @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息

一.导入pom文件

<!--Swagger-UI API文档生产工具-->
<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>

二.添加Swagger-UI的配置

 

package com.huawei.config;

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 jose
 * date 2020
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.huawei.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("mall-tiny")
                .contact("macro")
                .version("1.0")
                .build();
    }

}

三.编写Controller类

package com.huawei.controller;

import com.huawei.pojo.Teacher;
import com.huawei.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.ArrayList;
import java.util.List;


/**
 * @Author jose
 * date 2020
 */
@Api(tags = "CheckCenterController", description = "客服接口")
@Controller
@RequestMapping("/checkcenter")
public class CheckCenterController {

    private static final Logger LOGGER = LoggerFactory.getLogger(CheckCenterController.class);

    @ApiOperation(value="获取用个人用户信息", notes="根据用户id获取客服")
    @ResponseBody
    @GetMapping("/getUser")
    public User getUser(String id) {
        LOGGER.info("传入的参数为",id);
        User user = new User();
        user.setId("1");
        user.setName("小明");
        return user;
    }

    @ApiOperation(value="查询教师列表", notes="无")
    @ResponseBody
    @PostMapping("/selectTeacherList")
    public List<Teacher> selectTeacherList() {
        ArrayList<Teacher> list = new ArrayList<>();

        Teacher teacher = new Teacher();
        teacher.setTid(1);
        teacher.setName("王老师");
        teacher.setCid(1011);
        list.add(teacher);

        Teacher teacher2 = new Teacher();
        teacher2.setTid(2);
        teacher2.setName("张老师");
        teacher2.setCid(2022);
        list.add(teacher2);
        return list;
    }
}

四.实体类(使用@ApiModelProperty("教师id")注解)

package com.huawei.pojo;

import io.swagger.annotations.ApiModelProperty;

/**
 * @Author jose
 * date 2020
 */
public class Teacher {

    @ApiModelProperty("教师id")
    private int tid;

    @ApiModelProperty("教师名称")
    private String name;

    @ApiModelProperty("教师工号")
    private int cid;

    public int getTid() {
        return tid;
    }

    public void setTid(int tid) {
        this.tid = tid;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getCid() {
        return cid;
    }

    public void setCid(int cid) {
        this.cid = cid;
    }
}
package com.huawei.pojo;

import io.swagger.annotations.ApiModelProperty;

/**
 * @Author jose
 * date 2020
 */
public class User {
    @ApiModelProperty("用户id")
    private String id;
    @ApiModelProperty("用户姓名")
    private String name;
    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

五.启动类开启(@EnableSwagger2)

package com.huawei;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringbootHttpApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootHttpApplication.class, args);
    }

}

访问Swagger-UI接口文档地址: http://localhost:8080/swagger-ui.html#/

参考文档: http://www.macrozheng.com/#/architect/mall_arch_02?id=项目使用框架介绍

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部