springboot整合swagger

1. 引入依赖，之前引入的是3.0版本，但是一直访问不成功，所以降了个版本

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

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

2. swaggerConfig配置文件

package com.dbhd.model.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger配置
 */

@Configuration //标记为配置类
@EnableSwagger2 //开启Swagger在线接口文档
public class SwaggerConfig {
    /**
     * 添加摘要信息(Docket)
     * .groupName("XXXX")配置这个Docket的组名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
               // .groupName("组名:")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dbhd.model.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题:此处是配置UI界面显示的标题信息")
                .description("描述：这里配置的是UI界面显示的对这个接口文档的描述信息")
                //new Contact()  第一个参数是创建者,第二个是连接地址(可以不配),第三个参数是邮箱(可以不配)
                .contact(new Contact("leah", "", ""))
                .version("版本号:1.0")
                .build();
    }
}

3. controller使用

package com.dbhd.model.controller;

import com.dbhd.model.dto.UpdateEquipmentDto;
import com.dbhd.model.entity.Equipment;
import com.dbhd.model.dto.EquipmentDto;
import com.dbhd.model.enumeration.EquipmentType;
import com.dbhd.model.service.EquipmentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

@RestController
@Api(tags = "设备模块")
@RequestMapping("/equipment")
public class EquipmentController {
    @Resource
    EquipmentService equipmentService;

    @PostMapping("")
    @ApiOperation("添加设备")
    public Equipment save(@Validated @RequestBody EquipmentDto eq) {
        return equipmentService.save(eq.getName(), eq.getType(), eq.getOther().toString());
    }
    
    @GetMapping("")
    @ApiOperation(value = "根据名字或类型查看设备",notes = "type和name的值为空就返回所有设备列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "type", required = true),
            @ApiImplicitParam(name = "name", required = true)
    })
    public List<Equipment> getByTypeAndName(
            @RequestParam("type") EquipmentType type,
            @RequestParam("name") EquipmentType name
    ) {
        return equipmentService.getEquipmentByTypeAndName(type, name);
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "根据id查看")
    public List<Equipment> getBy(
            @PathVariable Integer id
    ) {
        return equipmentService.getEquipmentById(id);
    }
}

4. dto上使用
   注意：@ApiModel（value="表单名字"）中的value名字必须是唯一的，不然在swagger界面中会混乱

@Data
@ApiModel(value = "登录表单")
public class LoginDto {

    @ApiModelProperty(value = "用户名", required = true, example = "admin")
    @NotBlank(message = "用户名不能为空")
    private String username;

    @ApiModelProperty(value = "密码", required = true, example = "123456")
    @NotBlank(message = "密码不能为空")
    private String password;

}

5. 默认访问地址是：http://localhost:8080/swagger-ui.html

6. 如果项目上线并且需要关闭swagger接口，可以通过配置权限，或者再SwaggerConfig里面
   return new Docket的时候加多一个.enable(false)

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了。
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面。
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
• @ApiModelProperty： 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序。