springboot 整合swagger2

一、swagger的主要是用来干什么

swagger已经不算什么很新的框架了，基本上各大项目组都在用。主要作用就是很多人员会抱怨别人写的接口文档不规范，不及时更新。但是当自己写的时候确实最烦去写接口文档。
所以接口文档可以实时动态生成就不会出现上面问题

话不多说，直接开整

二、springboot整合swagger2

1、创建好一个springboot项目，加入依赖

    <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <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、Swagger2配置
只需要开发者自己提供一个Docket的Bean即可。
例如最简单的：

package com.dexin.config;

import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

/**
 * @author: 德鑫
 * Description:
 * @Date: 2021/03/03
 */

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
//                可以通过apis()方法设置哪个包中内容被扫描
                .apis(RequestHandlerSelectors.basePackage("com.dexin.controller"))
//                .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
                .paths(allowPaths())
                .build();
    }

    private Predicate<String> allowPaths(){
        return or(
                regex("/People/.*")
        );
    }

    private ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("德鑫的swagger", "http://www.dexinxxx.com", "xxx@163.com"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}

3、通过@EnableSwagger2注解启用Swagger2

package com.dexin;

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

@SpringBootApplication
@EnableSwagger2
public class Swagger2Application {

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

}

输入 http://localhost:8080/swagger-ui.html

三、swagger2常见的注解

1、@Api注解可以用来标记当前Controller的功能。
2、@ApiOperation注解用来标记一个方法的作用。
3、@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4、如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5、@ApiModel 是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。
-value：名称
-description：描述
6、@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
7、@ApiIgnore。@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略

那就把我自己写的一些测试代码放到上面来吧：  上面的SwaggerConfig 

package com.dexin.controller;

import com.dexin.anno.NotIncludeSwagger;
import io.swagger.annotations.*;
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.RestController;

import java.util.Objects;

/**
 * @author: 德鑫
 * Description:
 * @Date: 2021/03/03
 */
@RestController
@RequestMapping("/People")
@Api(tags = {"swagger的控制层"},description = "描述")
public class SwaggerController {
    @ApiOperation(value="接口描述",notes = "接口提示信息")
    @PostMapping("/getPeople")
    @ApiImplicitParam(name = "id",value = "id",required = true,paramType = "query",dataType = "string")
    public People getPeople(Long id, String name){
        System.out.println(id);
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("海淀");
        return peo;
    }

    @NotIncludeSwagger
    @GetMapping("/getPeople2")
    public People getPeople2(Long id , @ApiParam(value="姓名",required = true) String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("朝阳");
        return peo;
    }
}

@ApiModel(value = "人类",description = "描述")
class People {
    private Long id;
    @ApiModelProperty(value = "姓名",name = "name",required = true,example = "张三")
    private String name;
    private String address;

    public Long getId() {
        return id;
    }

    public People setId(Long id) {
        this.id = id;
        return this;
    }

    public String getName() {
        return name;
    }

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

    public String getAddress() {
        return address;
    }

    public People setAddress(String address) {
        this.address = address;
        return this;
    }

    @Override
    public String toString() {
        return "People{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", address='" + address + '\'' +
                '}';
    }

    @Override
    public boolean equals(Object o) {

        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        People people = (People) o;
        return Objects.equals(id, people.id) &&
                Objects.equals(name, people.name) &&
                Objects.equals(address, people.address);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, name, address);
    }
}

包括我们的自定义注解

package com.dexin.anno;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @author: 德鑫
 * Description:
 * @Date: 2021/03/03
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {

}

还有别忘了在我们项目的启动类上面添加 @EnableSwagger2 启动swagger2注解

好了就写到这里了。