zoukankan      html  css  js  c++  java
  • Spring Boot 入门实战(8)--使用 Swagger 构建 API 文档

    Swagger 是一个流行的API开发框架,该框架以"开放API声明"(OpenAPI Specification,OAS)为基础,对整个 API 的开发周期都提供了相应的解决方案。本文主要介绍 Spring Boot 与Swagger 的结合使用,文中所使用到的软件版本:Spring Boot 2.4.4、jdk1.8.0_181、springfox-swagger2 3.0.0。

    1、简介

    1.1、Swagger简介

    Swagger是一系列用于Restful API开发的工具,开源的部分包括:
    OpenAPI Specification:API规范,规定了如何描述一个系统的API
    Swagger Codegen:用于通过API规范生成服务端和客户端代码
    Swagger Editor:用来编写API
    Swagger UI:用于展示API
    非开源的部分包括:
    Swagger Hub:云服务,相当于Editor + Codegen + UI
    Swagger Inspector:手动测试API的工具
    SoapUI Pro:功能测试和安全测试的自动化工具
    LoadUI Pro:压力测试和性能测试的自动化工具

    1.2、Springfox简介

    Springfox是一个通过扫描代码提取代码中信息生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification,还有RAML,jsonapi,Springfox同样支持这些格式。Springfox实现了对Swagger注解的支持,并集成了Swagger UI。

    2、Swagger常用注解

    注解使用的地方用途
    @Api 描述类的主要用途
    @ApiOperation 方法 描述方法的用途
    @ApiImplicitParam 方法 用于描述接口的单个参数
    @ApiImplicitParams 方法 用于描述接口的参数集,包含多个@ApiImplicitParam
    @ApiIgnore 类/方法/参数 Swagger 文档不会显示拥有该注解的接口
    @ApiModel 参数实体类 描述参数实体类的主要用途
    @ApiModelProperty 参数实体类属性 描述参数实体类属性的主要用途
    @ApiResponse 方法 描述一个响应信息
    @ApiResponses 方法 描述一组响应信息

    3、Spring Boot 整合 Swagger

    3.1、引入依赖

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

    3.2、Swagger 配置

    package com.abc.demo.config;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.*;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.*;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    
    @Configuration
    @EnableOpenApi
    public class SwaggerConfig {
        private static final String AUTH_HEADER_NAME = "token";
    
        @Bean
        public Docket docket() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    //加了ApiOperation注解的方法,才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //特定包下的类,才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.abc.demo.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("XXX系统")
                    .description("XXX系统接口文档")
                    .termsOfServiceUrl("https://www.abc.com")
                    .contact(new Contact("Jack", "https://www.cnblogs.com/jack", "123456@qq.com"))
                    .version("1.0.0")
                    .build();
        }
    
    }

    3.3、编写Controller

    package com.abc.demo.controller;
    import com.abc.demo.entity.R;
    import com.abc.demo.entity.Student;
    import com.abc.demo.form.StudentForm;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.web.bind.annotation.*;
    
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Random;
    
    @RestController
    @RequestMapping("/api/student")
    @Api(tags = "学生相关接口")
    public class StudentController {
        private static Logger logger = LoggerFactory.getLogger(StudentController.class);
        @PostMapping("add")
        @ApiOperation("增加学生(json方式提交)")
        public R<Long> add(@RequestBody StudentForm studentForm) {
            logger.info("studentForm={}", studentForm);
            //TODO: service调用
    
            return R.ok(new Random().nextLong());
        }
    
    
        @PostMapping("add2")
        @ApiOperation("增加学生(form方式提交)")
        public R<Long> add2(StudentForm studentForm) {
            logger.info("studentForm={}", studentForm);
            //TODO: service调用
    
            return R.ok(new Random().nextLong());
        }
    
        @GetMapping("get")
        @ApiOperation("根据姓名查询学生")
        @ApiImplicitParam(name = "name", value = "学生姓名", dataTypeClass = String.class, required = true)
        public R<Student> get(String name) {
            logger.info("name={}", name);
            //TODO: service调用
    
            return R.ok(new Student(new Random().nextLong(), "杜甫", 21, 175));
        }
    
        @GetMapping("list")
        @ApiOperation("获取学生列表")
        public R<List<Student>> list() {
            //TODO: service调用
            List<Student> students = new ArrayList(){{
               add(new Student(new Random().nextLong(), "杜甫", 21, 175));
               add(new Student(new Random().nextLong(), "李商隐", 22, 175));
            }};
            return R.ok(students);
        }
    
    }

    Controller用到的参数实体类StudentForm:

    package com.abc.demo.form;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    import lombok.ToString;
    
    @Data
    @ToString
    @ApiModel(value = "学生表单")
    public class StudentForm {
        @ApiModelProperty(value = "姓名", example = "李白")
        private String name;
    
        @ApiModelProperty(value = "年龄", example = "20")
        private Integer age;
    
        @ApiModelProperty(value = "身高", example = "175")
        private Integer height;
    }

    Controller用到的实体类Student:

    package com.abc.demo.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    import lombok.ToString;
    
    @NoArgsConstructor
    @AllArgsConstructor
    @Data
    @ToString
    @ApiModel(value = "学生信息")
    public class Student {
        @ApiModelProperty(value = "学生id", example = "1234")
        private Long id;
    
        @ApiModelProperty(value = "学生姓名", example = "李白")
        private String name;
    
        @ApiModelProperty(value = "年龄", example = "20")
        private Integer age;
    
        @ApiModelProperty(value = "身高", example = "175")
        private Integer height;
    }

    Controller用到的返回对象R:

    package com.abc.demo.entity;
    
    
    /**
     * 返回数据
     */
    public class R<T> {
        /**
         * 返回码
         * 0 正常,其他异常
         */
        private int returnCode = 0;
    
        /**
         * 描述
         */
        private String description = "OK";
    
        /**
         * 结果数据
         */
        private T result;
    
        public int getReturnCode() {
            return returnCode;
        }
        public String getDescription() {
            return description;
        }
        public T getResult() {
            return result;
        }
    
        public static R ok() {
            return new R();
        }
    
        public static <T> R<T> ok(T result) {
            R<T> r = new R<>();
            r.result = result;
            return r;
        }
        
        public static <T> R<T> error() {
            R<T> r = new R();
            r.returnCode = -1;
            r.description = "未知异常,请联系管理员";
            return r;
        }
    
        public static <T> R<T> error(String description) {
            R<T> r = new R();
            r.returnCode = -1;
            r.description = description;
            return r;
        }
        
        public static <T> R<T> error(int returnCode, String description) {
            R<T> r = new R();
            r.returnCode = returnCode;
            r.description = description;
            return r;
        }
    
    }
    R.java

    3.4、查看接口信息

    访问 http://localhost:8080/swagger-ui/index.html,就可以在页面查看并测试接口了:

    3.5、Swagger 带 Token 访问

    在很多应用中访问接口需要传token来验证登录情况,可以先访问不要token的接口(如登录接口)来获取token,然后用该token来访问接口,在 Swagger 中有两种方式来传token。

    3.5.1、全局token

    设置一个全局的token,每次请求时会把这个token加上。

    package com.abc.demo.config;
    
    import io.swagger.annotations.ApiOperation;
    import io.swagger.models.auth.In;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.*;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.*;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.contexts.SecurityContext;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import java.util.ArrayList;
    import java.util.Arrays;
    import java.util.List;
    
    
    @Configuration
    @EnableOpenApi
    public class SwaggerConfig {
        private static final String AUTH_HEADER_NAME = "token";
    
        @Bean
        public Docket docket() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    //加了ApiOperation注解的方法,才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //特定包下的类,才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.abc.demo.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    //设置全局token
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("XXX系统")
                    .description("XXX系统接口文档")
                    .termsOfServiceUrl("https://www.abc.com")
                    .contact(new Contact("Jack", "https://www.cnblogs.com/jack", "123456@qq.com"))
                    .version("1.0.0")
                    .build();
        }
    
        private List<SecurityScheme> securitySchemes() {
            return Arrays.asList(new ApiKey(AUTH_HEADER_NAME, "auth", In.HEADER.name()));
        }
    
        private List<SecurityContext> securityContexts() {
            List<SecurityContext> securityContexts = new ArrayList<>();
            securityContexts.add(SecurityContext
                    .builder()
                    .securityReferences(securityReferences())
                    .operationSelector(operationContext -> operationContext.requestMappingPattern().startsWith("/api/"))
                    .build());
            return securityContexts;
        }
    
        private List<SecurityReference> securityReferences() {
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[] {new AuthorizationScope("global", "accessEverything")};
            List<SecurityReference> securityReferences = new ArrayList<>();
            securityReferences.add(new SecurityReference(AUTH_HEADER_NAME, authorizationScopes));
            return securityReferences;
        }
    
    }

    效果如下:

    3.5.2、每个接口单独传token

    package com.abc.demo.config;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.*;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    import springfox.documentation.service.*;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import java.util.Arrays;
    import java.util.List;
    
    
    @Configuration
    @EnableOpenApi
    public class SwaggerConfig {
        private static final String AUTH_HEADER_NAME = "token";
    
        @Bean
        public Docket docket() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    //加了ApiOperation注解的方法,才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //特定包下的类,才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.abc.demo.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    //每个接口传token
                    .globalRequestParameters(globalRequestParameters());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("XXX系统")
                    .description("XXX系统接口文档")
                    .termsOfServiceUrl("https://www.abc.com")
                    .contact(new Contact("Jack", "https://www.cnblogs.com/jack", "123456@qq.com"))
                    .version("1.0.0")
                    .build();
        }
    
        private List<RequestParameter> globalRequestParameters() {
            return Arrays.asList(new RequestParameterBuilder()
                    .name(AUTH_HEADER_NAME)
                    .description("access token")
                    .in(ParameterType.HEADER)
                    .required(false)
                    .build());
        }
    
    }

    效果如下:



  • 相关阅读:
    Unity C# 反编译
    java finalize方法总结、GC执行finalize的过程
    Android性能调优篇之探索垃圾回收机制
    深入理解JVM(一)——JVM内存模型
    Android性能调优篇之探索JVM内存分配
    HashMap实现原理分析
    [干货]2017已来,最全面试总结——这些Android面试题你一定需要
    2017年最全的30个Android面试题,你将如何回答?
    Android2017进阶知识点、面试题及答案(精选版)
    Android2017最新面试题(3-5年经验个人面试经历)
  • 原文地址:https://www.cnblogs.com/wuyongyin/p/14646698.html
Copyright © 2011-2022 走看看