Swagger入门

Swagger入门

本文参考： https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/

Spring Boot 框架是目前非常流行的微服务框架，我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了展示如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。

一，Swagger简介

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分：

1. Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
2. Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
3. Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

二，使用Swagger

2.1 添加依赖

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.0</version>
        </dependency>

2.2 创建配置类

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

/**
 * @Author lmc
 * @Description
 * @Date: Create in 22:05 2020/8/24
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * 配置扫描接口
     * @return
     */
    @Bean
    public Docket createRestApi() {
        //设置要显示的swagger环境
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //RequestHandlerSelectors.basePackage指定要扫描的包
                //any()扫描全部
                //none()全部不扫描
                //withMethodAnnotation:扫描方法上的注解
                //withClassAnnotation:扫描类上的注解
                .apis(RequestHandlerSelectors.basePackage("com.lmc.controller"))
                //paths 过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置swagger信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Lmc TEST")
                .description("Lmc TEST Restful API")
                .contact(new Contact("lmc", "", "limincong@163.com"))
                .termsOfServiceUrl("http://localhost:6000/")
                .version("1.0")
                .build();
    }
}

2.3 创建测试接口

package com.lmc.controller;

import com.lmc.beans.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author lmc
 * @Description
 * @Date: Create in 22:11 2020/8/25
 */
@RestController
public class TestController {

    @GetMapping("/test")
    public String test() {
        return "test ...";
    }

    @GetMapping("/hello")
    public String hello() {
        return "hello ...";
    }

}

访问 http://localhost:8080/swagger-ui.html

2.3 接口注释

2.3.1 创建实体类

package com.lmc.beans;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @Author lmc
 * @Description
 * @Date: Create in 22:59 2020/8/25
 */
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }
}

2.3.2 测试接口

    @PostMapping("/user")
    //ApiOperation接口,描述接口的
    @ApiOperation("Hello控制类")
    public User user(@ApiParam("用户名") String username){
        return new User();
    }

访问 http://localhost:8080/swagger-ui.html ，/user 接口出现注释。

未完待续…