springboot集成swagger2

最新推荐文章于 2023-08-29 01:01:51 发布

禅剑一如

最新推荐文章于 2023-08-29 01:01:51 发布

阅读量755

点赞数

分类专栏： springboot swagger2

本文链接：https://blog.csdn.net/zsx18273117003/article/details/94918036

版权

springboot 同时被 2 个专栏收录

46 篇文章 1 订阅

订阅专栏

swagger2

2 篇文章 0 订阅

订阅专栏

参考官方资料：http://springfox.github.io/springfox/docs/current/

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#schema

其他：https://dzone.com/articles/spring-boot-2-restful-api-documentation-with-swagg

一、创建项目

1.创建一个简单的maven项目springboot-swagger2

2.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">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.zsx</groupId>
    <artifactId>springboot-swagger2</artifactId>
    <version>1.0-SNAPSHOT</version>
    <properties>
        <java.version>11</java.version>
    </properties>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.4.RELEASE</version>
        <relativePath />
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- swagger2所需依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

二、配置swagger2

创建配置类Swagger2Config.java

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

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors
                        .basePackage("com.zsx.api.controller"))
                .paths(PathSelectors.regex("/.*"))
                .build().apiInfo(apiEndPointsInfo());
    }

    private ApiInfo apiEndPointsInfo() {
        return new ApiInfoBuilder().title("Spring Boot REST API")
                .description("User Management REST API")
                .contact(new Contact("zsx", "http://localhost:8080", "xxx@163.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

三、创建用户实体类

package com.zsx.entity;

import java.io.Serializable;

public class User implements Serializable {

    private String id;
    private String name;
    private Integer age;

    public User() {
    }

    public User(String id, String name, Integer age) {
        this.id = id;
        this.name = name;
        this.age = age;
    }

    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;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "User{" +
                "id='" + id + '\'' +
                ", name='" + name + '\'' +
                ", age='" + age + '\'' +
                '}';
    }
}

四、编写用户api接口

package com.zsx.api.controller;

import com.zsx.entity.User;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api/v1")
@EnableSwagger2
public class UserController {

    @ApiOperation(value = "根据id获取用户信息", notes = "id不能为空")
    @GetMapping("user/{id}")
    public User get(String id) {
        if ("123".equals(id)) {
            return new User("123", "zhangsan", 18);
        }
        return new User();
    }

    @PostMapping("user")
    public String insert(@RequestBody User user) {
        user.setId("1234");
        return user.getId();
    }

    @DeleteMapping("user/{id}")
    public String delete(@RequestBody User user) {
        user.setId("1234");
        return user.getId();
    }

    @PutMapping("user")
    public String update(@RequestBody User user) {
        user.setId("1234");
        return user.getId();
    }
}

五、创建引导类

package com.zsx;

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

@SpringBootApplication
public class Swagger2Application {

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

六、启动引导类

H:\JDK\jdk-11.0.3\bin\java.exe -XX:TieredStopAtLevel=1 -noverify -Dspring.output.ansi.enabled=always -Dcom.sun.management.jmxremote -Dspring.jmx.enabled=true -Dspring.liveBeansView.mbeanDomain -Dspring.application.admin.enabled=true "-javaagent:H:\JetBrains\IntelliJ IDEA 2019.1.3\lib\idea_rt.jar=54368:H:\JetBrains\IntelliJ IDEA 2019.1.3\bin" -Dfile.encoding=UTF-8 -classpath F:\IdeaProjects\springboot\springbootswagger2\target\classes;E:\maven\repository\org\springframework\boot\spring-boot-starter-web\2.1.4.RELEASE\spring-boot-starter-web-2.1.4.RELEASE.jar;E:\maven\repository\org\springframework\boot\spring-boot-starter\2.1.4.RELEASE\spring-boot-starter-2.1.4.RELEASE.jar;E:\maven\repository\org\springframework\boot\spring-boot\2.1.4.RELEASE\spring-boot-2.1.4.RELEASE.jar;E:\maven\repository\org\springframework\boot\spring-boot-autoconfigure\2.1.4.RELEASE\spring-boot-autoconfigure-2.1.4.RELEASE.jar;E:\maven\repository\org\springframework\boot\spring-boot-starter-logging\2.1.4.RELEASE\spring-boot-starter-logging-2.1.4.RELEASE.jar;E:\maven\repository\ch\qos\logback\logback-classic\1.2.3\logback-classic-1.2.3.jar;E:\maven\repository\ch\qos\logback\logback-core\1.2.3\logback-core-1.2.3.jar;E:\maven\repository\org\apache\logging\log4j\log4j-to-slf4j\2.11.2\log4j-to-slf4j-2.11.2.jar;E:\maven\repository\org\apache\logging\log4j\log4j-api\2.11.2\log4j-api-2.11.2.jar;E:\maven\repository\org\slf4j\jul-to-slf4j\1.7.26\jul-to-slf4j-1.7.26.jar;E:\maven\repository\javax\annotation\javax.annotation-api\1.3.2\javax.annotation-api-1.3.2.jar;E:\maven\repository\org\springframework\spring-core\5.1.6.RELEASE\spring-core-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-jcl\5.1.6.RELEASE\spring-jcl-5.1.6.RELEASE.jar;E:\maven\repository\org\yaml\snakeyaml\1.23\snakeyaml-1.23.jar;E:\maven\repository\org\springframework\boot\spring-boot-starter-json\2.1.4.RELEASE\spring-boot-starter-json-2.1.4.RELEASE.jar;E:\maven\repository\com\fasterxml\jackson\core\jackson-databind\2.9.8\jackson-databind-2.9.8.jar;E:\maven\repository\com\fasterxml\jackson\core\jackson-core\2.9.8\jackson-core-2.9.8.jar;E:\maven\repository\com\fasterxml\jackson\datatype\jackson-datatype-jdk8\2.9.8\jackson-datatype-jdk8-2.9.8.jar;E:\maven\repository\com\fasterxml\jackson\datatype\jackson-datatype-jsr310\2.9.8\jackson-datatype-jsr310-2.9.8.jar;E:\maven\repository\com\fasterxml\jackson\module\jackson-module-parameter-names\2.9.8\jackson-module-parameter-names-2.9.8.jar;E:\maven\repository\org\springframework\boot\spring-boot-starter-tomcat\2.1.4.RELEASE\spring-boot-starter-tomcat-2.1.4.RELEASE.jar;E:\maven\repository\org\apache\tomcat\embed\tomcat-embed-core\9.0.17\tomcat-embed-core-9.0.17.jar;E:\maven\repository\org\apache\tomcat\embed\tomcat-embed-el\9.0.17\tomcat-embed-el-9.0.17.jar;E:\maven\repository\org\apache\tomcat\embed\tomcat-embed-websocket\9.0.17\tomcat-embed-websocket-9.0.17.jar;E:\maven\repository\org\hibernate\validator\hibernate-validator\6.0.16.Final\hibernate-validator-6.0.16.Final.jar;E:\maven\repository\javax\validation\validation-api\2.0.1.Final\validation-api-2.0.1.Final.jar;E:\maven\repository\org\jboss\logging\jboss-logging\3.3.2.Final\jboss-logging-3.3.2.Final.jar;E:\maven\repository\org\springframework\spring-web\5.1.6.RELEASE\spring-web-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-beans\5.1.6.RELEASE\spring-beans-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-webmvc\5.1.6.RELEASE\spring-webmvc-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-aop\5.1.6.RELEASE\spring-aop-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-context\5.1.6.RELEASE\spring-context-5.1.6.RELEASE.jar;E:\maven\repository\org\springframework\spring-expression\5.1.6.RELEASE\spring-expression-5.1.6.RELEASE.jar;E:\maven\repository\io\springfox\springfox-swagger2\2.9.2\springfox-swagger2-2.9.2.jar;E:\maven\repository\io\swagger\swagger-annotations\1.5.20\swagger-annotations-1.5.20.jar;E:\maven\repository\io\swagger\swagger-models\1.5.20\swagger-models-1.5.20.jar;E:\maven\repository\com\fasterxml\jackson\core\jackson-annotations\2.9.0\jackson-annotations-2.9.0.jar;E:\maven\repository\io\springfox\springfox-spi\2.9.2\springfox-spi-2.9.2.jar;E:\maven\repository\io\springfox\springfox-core\2.9.2\springfox-core-2.9.2.jar;E:\maven\repository\net\bytebuddy\byte-buddy\1.9.12\byte-buddy-1.9.12.jar;E:\maven\repository\io\springfox\springfox-schema\2.9.2\springfox-schema-2.9.2.jar;E:\maven\repository\io\springfox\springfox-swagger-common\2.9.2\springfox-swagger-common-2.9.2.jar;E:\maven\repository\io\springfox\springfox-spring-web\2.9.2\springfox-spring-web-2.9.2.jar;E:\maven\repository\com\google\guava\guava\20.0\guava-20.0.jar;E:\maven\repository\com\fasterxml\classmate\1.4.0\classmate-1.4.0.jar;E:\maven\repository\org\slf4j\slf4j-api\1.7.26\slf4j-api-1.7.26.jar;E:\maven\repository\org\springframework\plugin\spring-plugin-core\1.2.0.RELEASE\spring-plugin-core-1.2.0.RELEASE.jar;E:\maven\repository\org\springframework\plugin\spring-plugin-metadata\1.2.0.RELEASE\spring-plugin-metadata-1.2.0.RELEASE.jar;E:\maven\repository\org\mapstruct\mapstruct\1.2.0.Final\mapstruct-1.2.0.Final.jar;E:\maven\repository\io\springfox\springfox-swagger-ui\2.9.2\springfox-swagger-ui-2.9.2.jar com.zsx.Swagger2Application

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.1.4.RELEASE)

2019-07-07 00:47:06.121  INFO 7420 --- [           main] com.zsx.Swagger2Application              : Starting Swagger2Application on zsx with PID 7420 (F:\IdeaProjects\springboot\springbootswagger2\target\classes started by admin in F:\IdeaProjects\springbootmongodb)
2019-07-07 00:47:06.123  INFO 7420 --- [           main] com.zsx.Swagger2Application              : No active profile set, falling back to default profiles: default
2019-07-07 00:47:08.148  INFO 7420 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2019-07-07 00:47:08.182  INFO 7420 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2019-07-07 00:47:08.182  INFO 7420 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.17]
2019-07-07 00:47:08.190  INFO 7420 --- [           main] o.a.catalina.core.AprLifecycleListener   : An older version [1.2.16] of the APR based Apache Tomcat Native library is installed, while Tomcat recommends a minimum version of [1.2.21]
2019-07-07 00:47:08.191  INFO 7420 --- [           main] o.a.catalina.core.AprLifecycleListener   : Loaded APR based Apache Tomcat Native library [1.2.16] using APR version [1.6.3].
2019-07-07 00:47:08.191  INFO 7420 --- [           main] o.a.catalina.core.AprLifecycleListener   : APR capabilities: IPv6 [true], sendfile [true], accept filters [false], random [true].
2019-07-07 00:47:08.191  INFO 7420 --- [           main] o.a.catalina.core.AprLifecycleListener   : APR/OpenSSL configuration: useAprConnector [false], useOpenSSL [true]
2019-07-07 00:47:09.256  INFO 7420 --- [           main] o.a.catalina.core.AprLifecycleListener   : OpenSSL successfully initialized [OpenSSL 1.0.2m  2 Nov 2017]
2019-07-07 00:47:09.492  INFO 7420 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2019-07-07 00:47:09.492  INFO 7420 --- [           main] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 3203 ms
2019-07-07 00:47:09.994  INFO 7420 --- [           main] pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method [public org.springframework.http.ResponseEntity<springfox.documentation.spring.web.json.Json> springfox.documentation.swagger2.web.Swagger2Controller.getDocumentation(java.lang.String,javax.servlet.http.HttpServletRequest)]
2019-07-07 00:47:10.197  INFO 7420 --- [           main] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
2019-07-07 00:47:10.418  INFO 7420 --- [           main] d.s.w.p.DocumentationPluginsBootstrapper : Context refreshed
2019-07-07 00:47:10.446  INFO 7420 --- [           main] d.s.w.p.DocumentationPluginsBootstrapper : Found 1 custom documentation plugin(s)
2019-07-07 00:47:10.497  INFO 7420 --- [           main] s.d.s.w.s.ApiListingReferenceScanner     : Scanning for api listing references
2019-07-07 00:47:10.706  INFO 7420 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2019-07-07 00:47:10.710  INFO 7420 --- [           main] com.zsx.Swagger2Application              : Started Swagger2Application in 5.64 seconds (JVM running for 7.909)

七、查看请求

1. 打开浏览器，查看请求http://localhost:8080/swagger-ui.html#/

到此集成swagger成功

注：

swagger 2.0 @Api description description（暂未验证）
官方解决方案：https://github.com/swagger-api/swagger-core/issues/1476
stackoverflow解决方案：https://stackoverflow.com/questions/38074936/api-annotations-description-is-deprecated