springboot整合swagger(Knife4j)(漫画)

Posted 2021-07-17 自行车在路上

导读：整合swagger，为前端方便对接，后端用代码也好写文档

漫画

整合swagger demo

demo项目结构

application.yml

server:
  port: 8887
  servlet:
    context-path: /hello
spring:
  application:
    name: hello

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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.5.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Swagger2Config.java

package com.example.demo.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;


/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("hello")
                .contact(new Contact("hello", null, null))
                .version("1.0")
                .build();
    }
}

QueryRequestDTO.java

package com.example.demo.dto.request;

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

@ApiModel("查询参数")
public class QueryRequestDTO {

    @ApiModelProperty(value = "id值",example = "1")
    String id;

    @ApiModelProperty(value = "名称",example = "xiaoming")
    String name;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

QueryResponseDTO.java

package com.example.demo.dto.response;

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

@ApiModel("返回参数")
public class QueryResponseDTO {

    @ApiModelProperty(value = "id值",example = "1")
    String id;

    @ApiModelProperty(value = "名称",example = "xiaoming")
    String name;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

HelloController.java

package com.example.demo.controller;

import com.example.demo.dto.request.QueryRequestDTO;
import com.example.demo.dto.response.QueryResponseDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api("hello中心")
public class HelloController {


    @ApiOperation(value = "hello信息")
    @PostMapping("/hello")
    public QueryResponseDTO hello(@RequestBody QueryRequestDTO dto){
        QueryResponseDTO responseDTO = new QueryResponseDTO();
        responseDTO.setId("1");
        responseDTO.setName("xiaowang");
        return responseDTO;
    }

    @GetMapping("/hello2")
    public String hello2(){
        return "hello,world2,how are you?";
    }

    @GetMapping("/hello3")
    public String hello3(){
        return "hello,world3,how are you?";
    }
}

DemoApplication.java

package com.example.demo;

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

@SpringBootApplication
public class DemoApplication {

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

效果访问

访问原生的swagger网址

http://localhost:8887/hello/swagger-ui/

稍微有点丑且不太好控制

访问knife4j的地址

http://localhost:8887/hello/doc.html

这种会好看点

demo项目 git地址

https://gitee.com/null_751_0808/spring-boot-demo/tree/spring-boot2-swagger2/
分支：spring-boot2-swagger2

Knife4j文档

https://doc.xiaominfo.com/knife4j/documentation/description.html

参考资料

还在手动整合Swagger？Swagger官方Starter是真的香！