springboot集成swagger2 API文档 接口方法一目了然 参数/返回类型基本数据类型/实体类类型 后续美化swagger UI

1 构建springboot项目(自行百度,灰常简单) 

引入依赖

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

 

2新增配置类

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

@Configuration//该注解表示这是一个配置类(其实就是名字上区别于@controller@service@mapper 这些)
@EnableSwagger2// 注解表示开启swagger
public class Swagger2Api {

    @Bean
    Docket createApi() {
        Docket build = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wenbin.springboot"))// 包扫描的地址
                .paths(PathSelectors.any())
                .build();
        return build;
    }

    @Bean
    ApiInfo getApiInfo() {
        return new ApiInfoBuilder().title("API文档").description("我的swagger文档2.0").termsOfServiceUrl("http://xxx.com").version("2.0").build();
    }
}

大致意思很简单都不多说了

3新增controller

package com.wenbin.springboot.springbootswagger2.controller;

import com.wenbin.springboot.springbootswagger2.pojo.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;


@Api(value = "helloController的api文档", description = "helloController的api文档2") // 描述一个类
@RequestMapping("/h")
@RestController
public class HelloController {

    @ApiOperation(value = "hello的入口方法,基本数据类型参数") // 描述一个方法
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    String getHello1(@ApiParam(name = "name", value = "姓名", required = true) @RequestParam(value = "name", required = true) String name) {
        return "Hello springboot!" + name;
    }


    @ApiOperation(value = "这是一个restful方法风格演示")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", dataType = "Long", required = true)
    String hello2(@PathVariable(value = "id", required = true) Long id) {
        return "my id is" + id;
    }

    @ApiIgnore// 取消扫描这个方法
    @RequestMapping(value = "/hello3", method = RequestMethod.GET)
    String hello3(@PathVariable(value = "id", required = true) Long id) {
        return "my id is" + id;
    }

    @ApiOperation(value = "这是一个参数为实体类的演示") //
    @RequestMapping(value = "/hello4", method = RequestMethod.GET)
    Student hello4(@RequestBody(required = false)@ModelAttribute Student student) {
        System.out.println("111 = " + 111);
        return new Student();
    }

}

需要注意一点: swagger注解的属性, name属性是表示在swagger中发送请求的参数,value和description才是类似描述的属性,和我们javaweb的属性其实有点相反的.比如 @requestMapping的value才是 请求的相对路径,编写的时候一定要注意哈

这里要解释下注解;

@Api(value = "helloController的api文档",description = "helloController的api文档2") // 描述一个类
放在类或者接口类上面 description就是描述,会展示在页面上


@ApiOperation(value = "hello的入口方法,基本数据类型参数") // 描述一个方法
放在方法 或者接口方法上 常用属性 value

@ApiParam(name = "name", value = "姓名",required = true)
放在参数前面 name属性是在swagger文档上运行时传的值 value是传的值

@ApiImplicitParam(name = "id",value = "用户id",paramType = "path",dataType = "Long",required = true)
如果构建的是restFul风格这个要注意需要注意paramType 和 datatype这两个属性,填错的话 项目启动开始扫描失败  会报错实体类

重点标注下实体类相关注解

@ModelAttribute 标注在参数类型为实体类的上面

@ApiModel(description = "学生",value = "student") 
@ApiModelProperty(name = "id", value = "学生id",dataType = "Long",required = true)

看一下实体类的标注吧(实际上还有一种注解,但是参数为实体类的方法上都要加就比较繁琐了,这样给一个实体类上加上一劳永逸)

package com.wenbin.springboot.springbootswagger2.pojo;

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

@ApiModel(description = "学生",value = "student")
public class Student {

    @ApiModelProperty(name = "id", value = "学生id",dataType = "Long",required = true)
    private Long id;
    @ApiModelProperty(name = "name", value = "学生姓名",required = true)
    private String name;
    @ApiModelProperty(name = "age", value = "年龄")
    private Integer age;

    //省略下getset
}

4启动,查看文档样式

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

这里重点截图下参数为 实体类的

 

==============

=[美化]=

添加依赖

       <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

把swagger-ui.html 改为 doc.html  

效果: