springboot集成swagger2或swagger3

swagger2的使用

1.导入swagegr2和swagegr-ui的依赖

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

版本较高的springboot项目，启动会报java.lang.NullPointerException错误
关注WebMvcProperties中的Pathmatch，根据注册的映射选择匹配请求路径的策略。

//默认为PATH_PATTERN_PARSER
private MatchingStrategy matchingStrategy = MatchingStrategy.PATH_PATTERN_PARSER;

默认PATH_PATTERN_PARSER，改为使用AntPathMatcher实现。可解决空指针异常问题

#application.properties中配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.添加SwaggerConfig类并配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//创建该Api的基本信息（这些基本信息会展现在文档页面中）
                .groupName("No.1")  //团队名，默认是default。
                .select()//函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger ui来展现
                .apis(RequestHandlerSelectors.basePackage("com.baidu.springboot07swagger2.controller"))//指定需要扫描的包路路径
//              .paths(PathSelectors.ant("/c2/**"))//匹配/c2/开头的所有controller
                .build();				//建造者模式，建造
    }
    //配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("BASIHUN","https://www.cnblogs.com/baishun666/","1@qq.com");
        return new ApiInfo(
                "swagger测试-API接口文档",
                "Api Documentation",
                "version1.0",
                "https://www.cnblogs.com/baishun666/",
                contact,
                "license:Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

注意：
1）swagger2需要添加@EnableSwagger2注解
2）swagger2在线测试接口，接口查看地址可以通过服务地址 /swagger-ui.html 来访问，例如http://localhost:8080/swagger-ui.html
3）在SwaggerConfig下创建多个Docket对象，并设置不同的groupName可以模拟多人协作开发

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    //多人协作开发，多个Docket实例，扫描不同的接口
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }

4）.enable()是否开启swagger的ui页面，默认为true，生产模式prod应该设置为false
5）.paths(PathSelectors.ant("/c2/**"))代表只让swagger获取到以/c2开头的controller请求
例如http://localhost:8080/c2/add、http://localhost:8080/c2/delete
6)ApiInfo可以通过return new ApiInfoBuilder()来修改信息

swagger3的使用

1.swagger3依赖导入

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>

同时也要在application.properties中添加spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.添加SwaggerConfig类并配置

@Configuration
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("baishun")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.baidu.springboot07swagger.controllers"))
                .build();
    }
    //配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("我的Api文档")
                .contact(new Contact("baishun","https://www.cnblogs.com/baishun666/","1@qq.com"))
                .version("1.0")
                .build();
    }
}

注意：
1）DocumentationType建议由DocumentationType.SWAGGER_2变为DocumentationType.OAS_30
2）浏览器访问ui界面地址变为http://localhost:port/swagger-ui/index.html

常用注解的使用

@Api
放在Controller类前，说明该类的作用。

@Api(tags = "User的Controller")  //注意，description已经弃用
public class UserController {
}

@ApiModel
用在类上，表示对类进行说明，用于实体类中的参数接收说明

@ApiModel(value = "com.pojo",description = "pojo->用户User")
public class User {
}

@ApiModelProperty()
用于字段，表示对 model 属性的说明

    @ApiModelProperty(value = "账号")
    private String name;
    @ApiModelProperty(value = "密码")
    private String password;

@ApiOperation
用在 Controller 里的方法上，说明方法的作用，每一个接口的定义

@ApiOperation(value = "新建用户")
    public User add(){
}