swagger2 -Api接口文档的生成

swagger2 -Api接口文档的生成

1.构建项目模块

2.添加项目的相关依赖,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>com.demo</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.0.RELEASE</version>
    </parent>
    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

    </dependencies>

</project>

3.配置文件(application.yml)中,修改端口号(默认为8080):

server:
  port: 9093

4.编写启动类

package com.demo.swaggerUi;

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

/**
 * @className: SwaggerApplication
 * @description: 接口文档
 * @author: penghailan
 * @create: 2021-04-02 13:42
 **/
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

启动项目,看项目是否能够正常启动

5.编写Swagger-UI配置类

注意：RequestHandlerSelectors.basePackage("com.smedic.admin.controller") 为 Controller 包路径，不然生成的文档扫描不到接口

创建一个名为 SwaggerUiConfig的 Java 配置类，代码如下：

package com.demo.swaggerUi.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * @className: SwaggerUiConfig
 * @description: swagger配置
 * @author: penghailan
 * @create: 2021-04-02 13:44
 **/
@EnableSwagger2
@Configuration
public class SwaggerUiConfig {
    @Bean
    public Docket createRestApi(){
        ParameterBuilder token = new ParameterBuilder();
        ParameterBuilder userId = new ParameterBuilder();
        ArrayList<Parameter> pars = new ArrayList<>();
        token.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        userId.name("userId").description("userId").modelRef(new ModelRef("integer")).parameterType("header").required(false).build();
        pars.add(token.build());
        pars.add(userId.build());
        ApiInfo apiInfo = new ApiInfoBuilder()
                //页面标题
                .title("swagger api 文档")
                //版本号
                .version("1.0")
                //描述
                .description("测试restful api接口文档")
                .build();
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("com.demo.swaggerUi.controller"))// 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外
                .paths(PathSelectors.any()).build().globalOperationParameters(pars);
    }
}

6.使用 Swagger2

编写测试Controller,并在controller 中增加 Swagger2 相关注解，示例代码如下：

package com.demo.swaggerUi.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @className: TestController
 * @description: 测试
 * @author: penghailan
 * @create: 2021-04-02 13:51
 **/
@RestController
@RequestMapping("test")
public class TestController {

    @ApiOperation(value = "swaggerUi",httpMethod = "GET",notes = "测试生成swaggerUi文档")
    @RequestMapping(value = "swaggerUi",method = RequestMethod.GET)
    public String testSwagger(){
        return "生成swaggerUi文档";
    }
}

7.访问 SwaggerUI

访问地址：http://ip:port/swagger-ui.html

例如:http://localhost:9093/swagger-ui.html