六、springboot整合swagger

六、springboot整合swagger

简介

swagger 提供最强大，最易用的工具，以充分利用OpenAPI规范。

官网 ： https://swagger.io/

准备工作

• pom.xml jar引入： <swagger.version>2.9.2</swagger.version>

     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

目的

之前使用swagger都是直接在类，方法，实体上写api引入的参数，这给人一种代码很不清爽的感觉，所以采用yaml文件编辑的模式，是代码看着更简单。

项目结构

• 1.创建SwaggerConfig类

package com.honghh.bootfirst.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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * ClassName: SwaggerConfig
 * Description:
 *
 * @author honghh
 * @date 2019/02/20 14:28
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，生成接口文档
                //.apis(RequestHandlerSelectors.basePackage("com.honghh.bootfirst.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("boot-demo")
                .description("boot-demo文档")
                .termsOfServiceUrl("http://www.boot-demo.cn")
                .version("1.0.0")
                .build();
    }

}

• 2.引入swagger展示层代码，代码我将上传到码云 https://gitee.com/honghh/boot-demo.git
• 3.配置yaml文件

#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: ‘2.0‘
#必要字段！描述API接口信息的元数据
info:
  #接口文档的描述
  description: swagger说明文档，让一切都变得如此简单。
  #版本号
  version: 1.0.0
  #接口标题
  title: boot-demo
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: localhost:8080
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
#basePath: /boot-demo

#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
  - https

#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性
produces:
  - application/json

#定义接口数据
paths:
  /myInfo:
    #必要字段!定义HTTP操作方法，必须是http协议定义的方法
    get:
      tags:
        - MyInfo 用户信息
      #接口概要
      summary: 用户信息
      #接口描述
      description: 查询出所有用户的所有信息，用户名，别名
      parameters:
        - name: id
          description: 用户ID
          in: query
          type: integer
          required: true
      #返回值描述，必要自动
      responses:
        #返回的http状态码
        200:
          description: 所有用户信息或者用户的集合信息
          #描述返回值
          schema:
            #返回值格式，可选的有array,integer,string,boolean
            $ref: ‘#/definitions/myInfo‘

#定义数据模型
definitions:
  R:
    type: object
    properties:
      code:
        description: 状态码 0：成功  非0：失败
        type: integer
        format: int32
      msg:
        description: 失败原因
        type: string
  myInfo:
    type: object
    properties:
      id:
        description: ID
        type: integer
        format: int32
      age:
        description: 年龄
        type: integer
      name:
        description: 姓名
        type: string

4.启动项目，输入：http://localhost:8080/swagger/index.html 运行如图


有关yaml编写的规范以及字段的意义，这里我就不一一说明，参考上面yaml文件中的注释，或参考下面文章，再不然就自行百度

参考文献

• Swagger编写API文档的YAML中文示例 https://blog.csdn.net/u010466329/article/details/78522992
• YAML、YML在线编辑器(格式化校验)
  http://www.bejson.com/validators/yaml_editor/

文章来源： https://blog.csdn.net/qq_35098526/article/details/87802697

原文地址：https://blog.51cto.com/11681903/2355858