springboot集成swagger2(1)

一、介绍

　　Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。通过swagger可以在线生成接口文档，便于测试。

　　swagger官网地址：https://swagger.io/

二、使用

　　1.maven依赖

配置方式一：       
       <!-- knife4j swagger  -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.2</version>
        </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>


方式三：

　　　　<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency> 
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.0</version>
        </dependency>

　　2.配置代码

　　2.1方式一　

　　

 　　2.2配置代码

# swagger
spring.swagger.enabled=true
spring.swagger.title=MySwagger2 
spring.swagger.description=Swagger_test
spring.swagger.version=v1
spring.swagger.contactName=MyTest

package com.config.swagger.properties;


import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

/**
 *   @author CMD
 * @ConfigurationProperties : 解释https://www.cnblogs.com/FraserYu/p/11261916.html
 */

@Data
@ConfigurationProperties("spring.swagger")
public class SwaggerProperties {

    /** 文档页标题 */
    private String title;

    /** 描述 */
    private String description;

    /** 版本号 */
    private String version;

    /** 条款地址(不可见)，公司内部使用的话不需要配 */
    private String termsOfServiceUrl;

    /** 联系人名字 */
    private String contactName;

    /** 联系人网址 */
    private String contactUrl;

    /** 联系人邮箱 */
    private String contactEmail;
}

package com.config.swagger;

import com.config.swagger.properties.SwaggerProperties;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.Api;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
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;


/**
 * @author CMD
 * @EnableSwagger2  使用swagger2构建restful接口测试
 * @EnableKnife4j   swagger升级版，ui更加丰富
 * @EnableConfigurationProperties的作用: 使@ConfigurationProperties 注解的类生效   https://blog.csdn.net/zhlin110228323/article/details/104351639
 * @ConditionalOnProperty   https://www.cnblogs.com/secbro/p/12011522.html
 */
@Slf4j
@EnableSwagger2
@EnableKnife4j
@Configuration
@EnableConfigurationProperties({SwaggerProperties.class})
@ConditionalOnProperty(prefix = "spring.swagger", name = {"enabled"}, havingValue = "true")
public class SwaggerConfiguration {


    /**
     *  创建API的基本信息(这些基本信息会展现在文档页面中)
     *  访问地址：http://项目实际地址/swagger-ui.html
     * @param swaggerProperties
     * @return
     */
    private ApiInfo apiInfo(SwaggerProperties swaggerProperties){

        ApiInfo build = new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())                                //api标题
                .description(swaggerProperties.getDescription())                    //api描述
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))  //本API负责人的联系信息
                .version(swaggerProperties.getVersion())                            //版本号
                .build();
        return build;
    }

    /**
     *  创建Api应用
     *      apiInfo()  增加API相关信息
     *      通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给swagger来展示
     *      可以使用指定扫描的包路径来定义指定要建立API的目录或者扫描注解的方式
     * @param swaggerProperties
     * @return
     */
    @Bean
    public Docket configure(SwaggerProperties swaggerProperties){
        Docket build = new Docket(DocumentationType.SWAGGER_2)                                      //文档类型（swagger2）
                .pathMapping("/")
                .apiInfo(this.apiInfo(swaggerProperties))                      //设置包含在json ResourceListing响应中的api元信息
                .select()                                                      //启动用于api选择的构建器
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  // 扫描注解  或者扫描包(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                .paths(PathSelectors.any())                                    //路径过滤器（扫描所有路径）
                .build();

        return build;
    }
}

　　2.3 接口配置

　　常用注解：

注解	使用地方	用途
@Api	类/接口	描述类/接口主要用途
@ApiOperation	方法	描述方法的用途
@ApiImplicitParam	方法	用于描述接口的非对象参数
@ApiImplicitParams	方法	用于描述接口的非对象参数集
@ApiIgnore	类/方法/参数	Swagger 文档不会显示拥有该注解的接口
@ApiModel	参数实体类	可设置接口相关实体的描述
@ApiModelProperty	参数实体类属性	可设置实体属性的相关描述

　　实体类：

package com.model;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Builder;
import lombok.Data;


/**
 *
 *  @JsonIgnoreProperties(ignoreUnknown = true) 防止值转化数量对不上报错
 *  @JsonInclude(JsonInclude.Include.NON_NULL)   为null的字段不显示
 * @author cmd
 */
@ApiModel
@Builder
@JsonIgnoreProperties(ignoreUnknown = true)
@Data
public class User {

    @ApiModelProperty(value = "用户id")
    private   String  id;

    @ApiModelProperty(value = "用户姓名")
    private   String   name;

    @ApiModelProperty(value = "用户年龄")
    private   Integer  age;


}

　　接口：

package com.controller;

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.model.User;
import com.wanda.framework.api.dto.response.ResultDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author cmd
 */
@Slf4j
@RestController
@Api(tags = "测试相关")
public class LogTestController {

    @ApiOperation(value = "测试用户请求")
    @ApiOperationSupport(order = 1)
    @RequestMapping(value = "/test/add",method = RequestMethod.GET,produces= MediaType.APPLICATION_JSON_UTF8_VALUE)
    public ResultDTO<User> getString(){
        User  user = User.builder()
                .id("20")
                .name("小明")
                .age(30).build();
        return ResultDTO.ok(user);
    }


}

　　访问地址：

　　　　http://localhost:9089/doc.html

　　最终结果：

 　　可能会出现的异常：

　　　　

 　　解决方式：查看在配置文件中是否存在  且结果为true。

     参看文档：https://www.jianshu.com/p/002ce2f26103

　　　　　　  https://blog.csdn.net/weixin_43333483/article/details/98958370

　　　　　　  https://www.cnblogs.com/progor/p/13297904.html#swagger%E7%9A%84%E4%BB%8B%E7%BB%8D

　　　　　　  https://segmentfault.com/a/1190000019992760