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

posted @ 2021-01-21 18:13 stt101517 阅读(76) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

stt101517

springboot集成swagger2(1)

一、介绍

二、使用

1.maven依赖

2.配置代码

2.1方式一

2.2配置代码

2.3 接口配置

实体类：

接口：

访问地址：

最终结果：

公告

　　1.maven依赖

　　2.配置代码

　　2.1方式一　

　　2.2配置代码

　　2.3 接口配置

　　实体类：

　　接口：

　　访问地址：

　　最终结果：