在SpringBoot项目中配置swagger接口文档

之前在项目中一直用到swagger,但是都是已经配置好的直接用就可以了,今天打算自己配置一次swagger,也是进一步学习理解吧.

本篇博客是为SpringBoot项目配合swagger,以提供在线测试接口的功能.

1. 在pom.xml文件中引入swagger依赖.

    <!-- 配置swagger -->
        <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>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>


        <!--解决进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21版本-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

2. 创建swagger配置

1) 实体类

package com.mbyte.easy.properties;

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

/**
 * @ClassName SwaggerProperties
 * @Description : swagger配置类
 * @Version 1.0
 * @Author : R
 * @Date : 2020/8/12 11:10
 */
@Component
@ConfigurationProperties(prefix = "swagger")
@Data
public class SwaggerProperties {
    //页面标题
    private String title;
    //创建人
    private String contactName;
    private String contactUrl;
    private String contactEmail;
    //版本号
    private String version;
    //描述
    private String description;
    //为当前包路径
    private String basePackage;

}

2) 配置类 

package com.mbyte.easy.config;

import com.mbyte.easy.properties.SwaggerProperties;
import org.springframework.beans.factory.annotation.Autowired;
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;

/**
 * @ClassName SwaggerConfig
 * @Description : Swagger2配置
 * @Author : R
 * @Date : 2020/8/12 11:22
 * @Version 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径 .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .paths(PathSelectors.any())
                .build();
Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(),swaggerProperties.getContactEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .build();
    }
}

3. 在yml配置文件中写入swagger配置信息

#swagger配置
swagger:
  title: 学习系统 REST API
  description: 这里是swagger接口
  version: 1.0
  contactName: right
  contactEmail:
  contactUrl:
  basePackage: com.mbyte.easy.rest

• ---

  此次配置是基于配置文档的,如果不采用配置文档的形式,可以直接在swagger配置类中直接写入就可以了,但是这里要注意,需要把swagger配置类和application启动类放在同一级目录下.

package com.mbyte.easy.config;

import com.mbyte.easy.properties.SwaggerProperties;
import org.springframework.beans.factory.annotation.Autowired;
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;

/**
 * @ClassName SwaggerConfig
 * @Description : Swagger2配置
 * @Author : R
 * @Date : 2020/8/12 11:22
 *  * @Version 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean  
    public Docket createRestApi() {// 创建API基本信息  
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.mbyte.easy.rest"))
     // 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外  
                .paths(PathSelectors.any())  
                .build();  
    }  

    private ApiInfo apiInfo() {// 创建API的基本信息，这些信息会在Swagger UI中进行显示  
        return new ApiInfoBuilder()  
            .title("学习系统 REST API")// API 标题  
            .description("这里是swagger接口")// API描述  
            .contact("right")// 联系人  
            .version("1.0")// 版本号  
            .build();  
    }  

}

 

---

4.  在接口类中写入注解,用来使用swagger接口文档

package com.mbyte.easy.rest.personInformation;

import com.mbyte.easy.admin.entity.PersonInformation;
import com.mbyte.easy.admin.service.IPersonInformationService;
import com.mbyte.easy.common.controller.BaseController;
import com.mbyte.easy.common.web.AjaxResult;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RestController;

import org.springframework.web.bind.annotation.*;

@Api(value = "个人信息接口", tags = {"个人信息接口"})
@RestController
@RequestMapping("rest/personInformation")
public class RestPersonInformationController extends BaseController  {

    @Autowired
    private IPersonInformationService personInformationService;

    /**
    * 删除
    * @param id
    * @return
    */
    @ApiResponses({@ApiResponse(code = 200, message = "正常", response = PersonInformation.class)})
    @ApiOperation(value = "根据当前用户id删除用户信息")
    @GetMapping("delete/{id}")
    public AjaxResult delete(@ApiParam(name = "id", value = "当前用户id", required = true)
            @PathVariable("id") Long id){
        return toAjax(personInformationService.removeById(id));
    }

}

其中,带有@Api的为swagger注解,这里写入的注解是我平常用到的,如果觉得不够还可以自行网上查找,是比较方便的.

5. 最后,启动项目,输入 localhost:端口号/swagger-ui.html 进入,可以在这里进行接口的测试,非常方便.效果是这样的:

 总体来说配置是比较简单的,共同学习吧!