Swagger的简单使用

待我称王封你为后i 2022-10-16 04:53 235阅读 0赞

Swagger是一个框架，可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。

光有文档还不够，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

本次使用基于全新的**swagger3.0**。

# pom.xml #

<?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">
        <modelVersion>4.0.0</modelVersion>
    
        <groupId>org.example</groupId>
        <artifactId>swagger-demo</artifactId>
        <version>1.0-SNAPSHOT</version>
    
        <properties>
            <maven.compiler.source>8</maven.compiler.source>
            <maven.compiler.target>8</maven.compiler.target>
            <spring-boot.version>2.3.4.RELEASE</spring-boot.version>
            <lombok.version>1.18.16</lombok.version>
            <swagger.fox.version>3.0.0</swagger.fox.version>
        </properties>
    
        <dependencies>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>${swagger.fox.version}</version>
            </dependency>
    
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
    
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </dependency>
        </dependencies>
    
        <dependencyManagement>
            <dependencies>
                
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-dependencies</artifactId>
                    <version>${spring-boot.version}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>
    
    </project>

# application.properties #

server.servlet.contextPath=/
    server.port=8080

# R.java #

package com.morris.swagger.vo;
    
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    import org.springframework.http.HttpStatus;
    
    import java.io.Serializable;
    
    @Data
    public final class R<T> implements Serializable { 
    
        private static final long serialVersionUID = 1L;
    
        @ApiModelProperty(value = "状态码", required = true, example = "200")
        private int code;
    
        @ApiModelProperty(value = "描述", required = true, example = "OK")
        private String message;
        private T result;
    
        private R() { 
        }
    
        private R(int code, String message, T result) { 
            this.code = code;
            this.message = message;
            this.result = result;
        }
    
        public static R ok() { 
            return new R(HttpStatus.OK.value(), HttpStatus.OK.getReasonPhrase(), null);
        }
    
        public static R ok(String msg) { 
            return new R(HttpStatus.OK.value(), HttpStatus.OK.getReasonPhrase(), null);
        }
    
        public static R ok(Object data) { 
            return new R(HttpStatus.OK.value(), HttpStatus.OK.getReasonPhrase(), data);
        }
    
        public static R fail() { 
            return new R(HttpStatus.INTERNAL_SERVER_ERROR.value(), HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(), null);
        }
    
        public static R fail(String msg) { 
            return new R(HttpStatus.INTERNAL_SERVER_ERROR.value(), msg, null);
        }
    
        public static R fail(int code, String msg) { 
            return new R(code, msg, null);
    
        }
    
        public static R fail(int code, String msg, Object data) { 
            return new R(code, msg, data);
    
        }
    
        public static R fail(Object data) { 
            return new R(HttpStatus.INTERNAL_SERVER_ERROR.value(), HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(), data);
        }
    
    }

# User.java #

package com.morris.swagger.vo;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    @ApiModel(value="user", description="user实体类")
    public class User { 
        @ApiModelProperty(value = "姓名", required = true, example = "morris")
        private String name;
    
        @ApiModelProperty(value = "年龄", required = true, example = "21")
        private Integer age;
    }

# UserController.java #

package com.morris.swagger.web;
    
    import com.morris.swagger.vo.User;
    import com.morris.swagger.vo.R;
    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.*;
    
    import java.util.ArrayList;
    import java.util.List;
    
    @RestController
    @RequestMapping("user")
    @Api(tags = "user相关接口")
    public class UserController { 
    
        @GetMapping("list")
        @ApiOperation("user列表")
        public R<User> list() { 
            List<User> users = new ArrayList<>();
            users.add(new User("morris", 19));
            users.add(new User("jack", 20));
            return R.ok(users);
        }
    
        @PostMapping("save")
        @ApiOperation("user保存")
        public R<Void> save(@RequestBody User user) { 
            return R.ok();
        }
    }

# SingleApp.java #

package com.morris.swagger;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.annotation.Bean;
    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;
    
    @SpringBootApplication(scanBasePackages = "com.morris.swagger.*")
    @EnableOpenApi //Enable open api 3.0.3 spec
    public class SingleApp { 
    
      public static void main(String[] args) { 
        SpringApplication.run(SingleApp.class, args);
      }
    
    
      @Bean
      public Docket createRestApi() { 
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.regex("(?!/error.*).*"))
                .build();
      }
    
      private ApiInfo apiInfo() { 
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("this is a description")
                .termsOfServiceUrl("http://springfox.io")
                .contact(new Contact("springfox", "https://morris131.github.io", "morris131@163.com"))
                .license("Apache License Version 2.0")
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                .version("3.0")
                .build();
      }
    
    }

# 演示 #

浏览器输入：[**http://localhost:8080/swagger-ui/index.html**][http_localhost_8080_swagger-ui_index.html]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMjI4MTI4NDk_size_16_color_FFFFFF_t_70]

# 代码地址 #

[**https://gitee.com/morris131/swagger-demo**][https_gitee.com_morris131_swagger-demo]

[http_localhost_8080_swagger-ui_index.html]: http://localhost:8080/swagger-ui/index.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMjI4MTI4NDk_size_16_color_FFFFFF_t_70]: /images/20221014/538df42268684e63bef41867d8616e45.png
[https_gitee.com_morris131_swagger-demo]: https://gitee.com/morris131/swagger-demo