Springboot集成swagger2（一）接口管理框架

Spring boot集成swagger构建接口管理文档

一，swagger简介

swagger是一个工具，用于自动生成web网站对外提供的服务接口文档，并且以web页面的形式进行展示。

优势：可以自动生成API文档  ，能降低前后端的沟通成本。

二，项目的基本结构

三，idea项目构建思路

3.1pom依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

   <groupId>com.yfy</groupId>
   <artifactId>bootsw</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>

   <name>bootsw</name>
   <description>Demo project for Spring Boot</description>

   <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>2.0.5.RELEASE</version>
      <relativePath/> <!-- lookup parent from repository -->
   </parent>

   <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
      <java.version>1.8</java.version>
   </properties>

   <dependencies>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>

      <!--swagge依赖-->
      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger2</artifactId>
         <version>2.6.1</version>
      </dependency>
      <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.6.1</version>
      </dependency>

      <!--lombok插件依赖-->
      <dependency>
         <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
         <version>1.16.10</version>
      </dependency>


   </dependencies>

   <build>
      <plugins>
         <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
         </plugin>
      </plugins>
   </build>


</project>

3.2application.properties配置

 3.3实体类

package com.yfy.bootsw.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "用户模型")
public class UserEntity {
    @ApiModelProperty(value="id" ,required= true,example = "123")
    private Integer id;
    @ApiModelProperty(value="用户姓名" ,required=true,example = "yyyy")
    private String name;


    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

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

    @Override
    public String toString() {
        return "DemoDoctor [id=" + id + ", name=" + name + "]";
    }
}

3.4Controller类

 

package com.yfy.bootsw;

import com.yfy.bootsw.entity.UserEntity;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@Api(value = "会员接口")
@RestController
public class AnimalController {
    @ApiOperation(value = "接口测试demo", nickname = "swagger接口测试demo昵称")
    @GetMapping("/getDemo")
  public String getDemo(){
    return "调用方法成功。。。。。";
  }
    @ApiOperation(value = "获取会员信息接口", nickname = "根据userName获取用户相关信息")
    @ApiImplicitParam(name = "userName", value = "用户名称", required = true, dataType = "String")
    @PostMapping("/postMember")
    public String postMember(@RequestParam String userName) {
        return userName;
   }
    @ApiOperation(value = "添加用户信息", nickname = "nickname是什么", notes = "notes是什么", produces = "application/json")
    @PostMapping("/postUser")
    @ResponseBody
    @ApiImplicitParam(paramType = "query", name = "userId", value = "用户id", required = true, dataType = "int")
    public UserEntity postUser(@RequestBody UserEntity user, @RequestParam("userId") int userId) {
        if (user.getId() == userId) {
            return user;
        }
        return new UserEntity();
    }
    @ApiOperation(value = "添加用户信息", nickname = "添加用户接口", notes = "测试添加用户的接口", produces = "application/json")
    @PostMapping("/addUser")
    @ResponseBody
    @ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "userName", value = "用户姓名", required = true, dataType = "String"), @ApiImplicitParam(paramType = "query", name = "id", value = "用户id", required = true, dataType = "int") })
    public UserEntity addUser(String userName, int id) {
        UserEntity userEntity = new UserEntity();
        userEntity.setName(userName);
        userEntity.setId(id);
        return userEntity;
    }

}

3.5config类的编写

package com.yfy.bootsw.config;

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;

@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // api扫包范围
                .apis(RequestHandlerSelectors.basePackage("com.yfy.bootsw")).paths(PathSelectors.any()).build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     *
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger接口发布测试").description("测试|Swagger接口功能")
                //服务条
                .termsOfServiceUrl("www.baidu.com")
                .contact(new Contact("yangjie", "https://blog.csdn.net/OnlyOneFrist", ""))
                .version("1.0")
                .build();
    }


}