springboot整合swagger3初体验

概述

日常的项目开发中无论是前端还是后端都会跟接口文档打交道,每一个开发者都期望有一个好的接口文档,但是实际开发过程中大家没少被接口文档折磨,前端抱怨后端给的接口文档不符合实际情况,后端觉得接口文档的编写和维护太麻烦,会浪费很多精力,故而不能做到实时的更新文档.为了解决这个痛苦于是有了swagger.swagger是一套对接口定义的规范,开发者只有按照其规范定义接口和接口相关信息, 然后通过Swagger自带的一些工具,就可以生成不同格式的接口文档

Swagger简介

官网

1.swagger提供的几种开源工具

• Swagger Codegen:通过扫描生成的json文件,生成接口调用代码
• Swagger UI:一个可视化的UI页面展示
• Swagger Editor:Swagger描述文件的编辑器,支持实时预览描述文件的更新效果
• Swagger Inspector:类型postman的作用,可以进行接口测试
• Swagger Hub:类似github,可将描述文件上传到swagger hub上面

springboot + swagger3

1.pom依赖

直接使用springfox

  <!--swagger3-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2.创建配置类

package com.hz.controll.config;

import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi(){
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //设置通过什么方式定位需要自动生产文档的接口,这里定位方法上的注解@ApiOperation注解
                //,RequestHandlerSelectors.basePackage()通过扫描包
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //接口URI路径设置,any是全路径,也可以通过pathSelectors.regex()正则匹配
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger3接口文档")
                .description("更多请咨询服务开发者子砚")
                .contact(new Contact("子砚","https://www.baidu.com","13928121916@163.com"))
                .version("1.2")
                .build();
    }
}

3.controller

package com.hz.controll;

import com.hz.dal.model.Clazz;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/clazz")
@Api(tags = "班级信息管理")
public class ClazzController {


    @ApiOperation(httpMethod = "GET",value = "根据班级编号查询班级信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "班级编号",required = true,paramType = "path",dataType = "Long")
    })
    @GetMapping(value = "/clazzs/getClazzById/{id}")
    public Clazz getClazzById(@PathVariable(value = "id",required = true)Long id){
        Clazz clazz = new Clazz();
        clazz.setId(1L);
        clazz.setName("高三(1)班");
        return clazz;
    }


}

4.相关注解说明

@Api:用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义。在I界面上也看到，所以不需要配置"

@Apioperation:用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用" 
    notes="方法的备注说明"

@ApiImplicitParams:用在请求的方法上，表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    name:参数名
    value:参数的汉字说明、解释
    required:参数是否必须传     
    paramType:参数放在哪个地方
        ·header>请求参数的获取:@RequestHeader
        .query>请求参数的获取:@RequestParam
        .path(用于restful接口)>请求参数的获取:@PathVariable.div(不常用)    
        .form(不常用)
dataType:参数类型，默认string，其它值dataType="Integer" defaultValue:参数的默认值
@ApiResponses:用在请求的方法上，表示一组响应
    @ApiResponse:用在@ApiResponses中，一般用 于表达一个错误的响应信息 
        code:数字，例如400
        message:信息，例如"请求参数没填好" 
        response:抛出异常的类
@ApiModel:用于响应类上，表示一个返回响应数据的信
        (这种一般用在post创建的时候，使用@ RequestBody这样的场景,
        请求参数无法使用@ApiImplicitParam往解进行描述的时候)
    @ApiModelProperty:用在属性上，描述响应类的属性

项目编写完成后本地启动项目,浏览器访问:
http://127.0.0.1:8080/swagger-ui/index.html

测试项目gitee地址