六、spring boot教程--集成swagger

一、swagger简介

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

1. Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

2. Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

3. Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

4. Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

5. Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

6. Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

二swagger使用方法

1.引入swagger的jar包

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

2.编写swagger配置类

在包com.core.deformation.config下新建Swagger2Config类，代码如下：

package com.core.deformation.config;

import io.swagger.models.Contact;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        Contact contact = new Contact();
        contact.setEmail("pin621@163.com");
        contact.setName("Api接口说明");
        contact.setUrl("localhost:8090");
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.core.deformation.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("形变监测")
                        .description("形变监测Api说明")
                        .version("1.0")
                        .contact("守望天命")
                        .license("The Apache License")
                        .licenseUrl("http://localhost:8090")
                        .build());
    }
}

3.控制器中代码

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

package com.core.deformation.controller;

import com.core.deformation.domain.Company;
import com.core.deformation.service.CompanyService;
import com.core.deformation.util.UUIDUtil;
import com.core.deformation.util.result.ResultUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Date;
import java.util.UUID;

@RestController
@RequestMapping("/api/company")
@Slf4j
@Api(tags = "单位管理相关接口")
public class CompanyController {

    @Autowired
    private CompanyService companyService;

    @GetMapping("/{id}")
    @ApiOperation("根据主键取得单位实体")
    @ApiImplicitParam(name = "id", value = "单位主键", required = true, dataType = "String", paramType = "path")
    public Company get(@PathVariable String id) {
        log.info("Get。。{}。。方法执行", id);
        return companyService.findById(id);
    }

    @DeleteMapping("/{id}")
    @ApiOperation("根据主键删除单位实体")
    @ApiImplicitParam(name = "id", value = "单位主键", required = true, dataType = "String", paramType = "path")
    public String delete(@PathVariable String id) {
        Company company = companyService.findById(id);
        return "删除成功";
    }

    @PostMapping
    @ApiOperation("添加单位实体")
    public Company save(@RequestBody Company company) {
        company.setCompanyId(UUIDUtil.getUUIDDispose());
        company.setCreateTime(new Date());
        company.setModifyTime(new Date());
        return companyService.save(company);
    }

    @PutMapping("/{id}")
    @ApiOperation("根据主键更新单位实体")
    @ApiImplicitParam(name = "id", value = "单位主键", required = true, dataType = "String", paramType = "path")
    public Company update(@PathVariable("id") String id, @RequestBody Company company) {
        return companyService.save(company);
    }
}

三、运行效果