前置技术: Swagger入门+配置类+方法配置+JavaBean配置+权限设置

最新推荐文章于 2024-03-22 21:47:58 发布

Eros1onz

最新推荐文章于 2024-03-22 21:47:58 发布

阅读量1k

点赞数 1

分类专栏： Swagger 文章标签： swagger java

本文链接：https://blog.csdn.net/Eros1onz/article/details/107070667

版权

Swagger 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

1. 前置技术: Swagger

1.1 Swagger介绍

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。https://github.com/OAI/OpenAPI-Specification
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 https://swagger.io
Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

总结：Swagger用于生成API接口工具或框架

1.2 Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下:

在这里插入图片描述

@ApiImplicitParam属性：

1.3 基于IDEA简单测试

修改pom文件:

<?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">
    <parent>
        <artifactId>xc_test_parent</artifactId>
        <groupId>com.czxy.xuecheng</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>test_swagger</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>


</project>

编写yml文件，配置端口号:

server:
  port: 8089 #服务端口

编写启动类:

package com.czxy.xuecheng.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

编写JavaBean:

package com.czxy.xuecheng.swagger.domain;

import lombok.Data;
@Data
public class User {
    private Integer uid;
    private String username;
    private String password;
}

编写测试controller:

package com.czxy.xuecheng.swagger.controller;

import com.czxy.xuecheng.swagger.domain.User;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/swagger")
public class SwaggerController {

    @GetMapping("/findAll")
    public List findAll(){
        List<String> list = new ArrayList<>();
        list.add("测试1");
        list.add("测试2");
        return list;
    }

    @GetMapping("/{id}")
    public String findById(@PathVariable String id){
        return "查询成功" + id;
    }

    @PostMapping
    public User save(@RequestBody User user){
        return user;
    }

}

页面访问:

2.1 Swagger 入门

2.1.1 Swagger 配置类

package com.czxy.xuecheng.swagger.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createApi(){
        // 1 确定文档Swagger版本
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // 2 设置 api基本信息
        docket.apiInfo( apiInfo() );

        // 3 设置自定义加载路径
        docket = docket.select()
                .apis(RequestHandlerSelectors.basePackage("com.czxy.xuecheng"))
                .paths(PathSelectors.any())
                .build();

        return docket;

    }

    /**
     * swagger-ui显示api基本信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学成网api文档")          			//标题
                .description("学成在线基于Swagger api文档") //描述
                .version("1.0")                				 //版本
                .build();
    }

}

在这里插入图片描述

2.1.2 类配置

在类上可以使用 @Api设置描述信息

@RestController
@RequestMapping("/demo")
@Api(tags = "入门程序接口",description = "这个Swagger入门程序的接口，提供基本CRUD操作")
public class DemoController {

在这里插入图片描述

2.1.3 方法配置

方法基本配置

@GetMapping("/findAll")
@ApiOperation("查询所有")
public List findAll(){

在这里插入图片描述

方法参数

@ApiImplicitParam(name="名称",value="描述",required = 是否必填,paramType = "参数类型",dataType = "数据类型")
//paramType取值
	header --> 请求参数的获取：@RequestHeader
     query --> 请求参数的获取：@RequestParam
     path（用于restful接口）--> 请求参数的获取：@PathVariable

@GetMapping("/{id}")
@ApiOperation("通过id查询详情")
@ApiImplicitParams({
     @ApiImplicitParam(name="id",value="唯一编号",required = true,paramType = "path",dataType = "String")
})
public String findById(@PathVariable String id){

在这里插入图片描述

2.1.4 JavaBean配置

package com.czxy.xuecheng.swagger.domina;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "User描述详细信息")
public class User {
    @ApiModelProperty(value = "唯一标识",required = true)
    private Integer uid;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

在这里插入图片描述

2.1.5 响应状态

@PostMapping
@ApiOperation("添加操作")
@ApiResponses({
    @ApiResponse(code = 400,message = "参数异常"),
    @ApiResponse(code = 500,message = "服务器端异常"),
    @ApiResponse(code = 20000,message = "自定义状态码异常")
})
public User save(@RequestBody User user){

在这里插入图片描述

2.1.6 设置权限

2.1.6.1 Swagger 配置

package com.czxy.xuecheng.swagger.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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createApi(){
        // 1 确定文档Swagger版本
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // 2 设置 api基本信息
        docket.apiInfo( apiInfo() );

        // 3 设置自定义加载路径
        docket = docket.select()
                .apis(RequestHandlerSelectors.basePackage("com.czxy.xuecheng"))
                .paths(PathSelectors.any())
                .build();
        //设置权限
        docket.securitySchemes(securitySchemes());
        docket.securityContexts(securityContexts());

        return docket;

    }

    /**
     * swagger-ui显示api基本信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学成网api文档")          			//标题
                .description("学成在线基于Swagger api文档") //描述
                .version("1.0")                				 //版本
                .build();
    }
    private List<ApiKey> securitySchemes() {
        List<ApiKey> list = new ArrayList<>();
        list.add(new ApiKey("Authorization", "Authorization", "header"));
        return list;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> list = new ArrayList<>();
        list.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$"))
                .build());
        return list;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> list = new ArrayList();
        list.add(new SecurityReference("Authorization", authorizationScopes));
        return list;
    }

}

2.1.7 设置token

在这里插入图片描述

Eros1onz

关注

1
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
前置技术: Swagger入门+配置类+方法配置+JavaBean配置+权限设置

1. 前置技术: Swagger1.1 Swagger介绍OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。https://github.com/OAI/OpenAPI-SpecificationSwagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个A
复制链接

扫一扫