7.SpringBoot开发实战-文档生成-swagger

Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。可以帮助我们设计、构建、记录以及使用 Rest API。

1.引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.编写配置文件类以及实体类和控制类

package com.duing.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;

/**
 * @Configuration
 * 首先声明是配置文件类
 * @EnableSwagger2
 * 开启swagger功能
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 使用swagger需要创建一个摘要 Docket
     * 摘要参数如下：
     * 文档类型（使用swagger2） DocumentationType.SWAGGER_2
     * 文档通过一系列选择器（规则）组成
     * select()选择器设置apis()和paths()
     * apis查找生成哪些controller的接口
     *      RequestHandlerSelectors.any()代表所有controller
     *      RequestHandlerSelectors.basePackage("")代表指定的包
     * paths在查找出来的接口中进行筛选  PathSelectors.any()所有接口
     * @return
     */
    @Bean
    public Docket api(){//声明一个摘要，让swagger可以显示出来
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.duing.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());//设置可视化界面的一些展示
    }

    /**
     * 自定义文档的介绍：标题，描述，版本等
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("spring-boot-06-swagger")
                .description("这是一个简单的swagger demo！")
                .version("1.0")
                .build();
    }

}

package com.duing.controller;

import com.duing.bean.Guest;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

/**
 * @RequestMapping("/guest")
 * 放在类的上面，表示类里面的方法都是以 /guest 开头的
 */
@RestController
@RequestMapping("/guest")
@Api(tags = "嘉宾相关的接口")//用在请求的类上，表示对类的说明
public class GuestController {


    //@RequestMapping(method = RequestMethod.GET)
    //等价于下面的注解
    @GetMapping
    @ApiOperation(value = "查询嘉宾列表",notes = "这是个备注")
    public String list(Model model){
        return "list";
    }

    @PostMapping
    @ApiOperation(value = "添加嘉宾")//用在请求的方法上，说明方法的用途、作用
    //@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    //@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    @ApiImplicitParams(
            {@ApiImplicitParam(name = "name",value = "嘉宾名字"),
            @ApiImplicitParam(name = "role",value = "嘉宾角色")})
    public String add(String name,String role){
        return "add guest";
    }

    @GetMapping("/toAdd")
    @ApiOperation(value = "用于跳转到添加嘉宾的界面")
    @ApiIgnore//不显示此接口
    public String toAdd(){
        return "add";
    }


    @GetMapping("/toUpdate/{name}")
    @ApiOperation(value = "跳转到修改嘉宾信息的界面")
    @ApiIgnore//不显示此接口
    public String toUpdate(@PathVariable("name") String name){
        return "update";
    }

    @PutMapping
    @ApiOperation(value = "修改嘉宾信息")
    public String update(Guest guest){
        return "update guest";
    }

    @DeleteMapping("/{name}")
    @ApiOperation(value = "删除嘉宾")
    public String delete(@PathVariable("name") String name){
        return "delete guest";
    }

}

package com.duing.bean;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
//@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModel("嘉宾")
public class Guest {

    @ApiModelProperty("嘉宾名字")
    private String name;
    @ApiModelProperty("嘉宾角色")
    private String role;
}

3.运行程序，打开下列网址
http://localhost:8080/swagger-ui.html 我们主要打开这个
http://localhost:8080/v2/api-docs