swagger配置

1.Spring MVC配置文件中的配置

 <mvc:annotation-driven/>

 <context:component-scan base-package="com.demo"/>

设置使用注解的类所在的jar包,只加载controller类

本身项目中已有此配置，就不要重复配置。

<mvc:default-servlet-handler />

使用 Swagger Restful API文档时，添加此注解

2. maven依赖

<properties>

           <servlet.version>3.1.0</servlet.version>

           <swagger2.version>2.5.0</swagger2.version>

</properties>

<dependencies>

        <!-- swagger开始  -->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>${swagger2.version}</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>${swagger2.version}</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-staticdocs</artifactId>

            <version>${swagger2.version}</version>

        </dependency>

        <!--  swagger结束  -->

        <!--web-->

        <dependency>

            <groupId>javax.servlet</groupId>

            <artifactId>javax.servlet-api</artifactId>

            <version>${servlet.version}</version>

            <scope>provided</scope>

        </dependency>

</dependencies>

3. Swagger注解配置

1.单个属性注解配置

@RequestMapping(value = "/add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户", notes = "增加用户")

public Result<UserVo> add(@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

 @ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,

      @ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {

     UserVo userVo=new UserVo();

     userVo.setUserId(System.currentTimeMillis());

     userVo.setUserName(userName);

        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

2.对象注解配置

@ApiOperation(value = "创建用户", notes = "根据UserVo对象创建用户")  

@RequestMapping(value = "/create", method = RequestMethod.POST)  

public String postUser(@ApiParam(required = true, name = "userVo", value = "实体UserVo") @RequestBody UserVo userVo) {  

        return "success";

 } 

 @RequestMapping(value = "/getUser", method = RequestMethod.GET)

 @ApiOperation(value = "获取用户", notes = "根据UserVo获取用户")  

 @ResponseBody

  public Result<UserVo> getUser() {  

     UserVo userVo=new UserVo();

     userVo.setUserId(System.currentTimeMillis());

     userVo.setUserName("UserName");

        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

 }

SwaggerConfig类编写示例

@Configuration

@EnableWebMvc （项目工程中需要增加此项注解配置，否则报错）

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket userApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("用户")

                .select()  // 选择那些路径和api会生成document

                .apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

                .paths(PathSelectors.any()) // 对所有路径进行监控

                .build()

                .apiInfo(userInfo());

    }

    private ApiInfo userInfo() {

        ApiInfo apiInfo = new ApiInfo("用户相关接口",//大标题

                "用户有关的接口，包括增加删除用户",//小标题

                "0.1",//版本

                "杭州",

                new Contact("zyx", "", ""),// 作者

                "swagger url",//链接显示文字

                ""//网站链接

        );

        return apiInfo;

    }

    @Bean

    public Docket otherApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("其它")

                .select()  // 选择那些路径和api会生成document

                .apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

                .paths(PathSelectors.any()) // 对所有路径进行监控

                .build()

                .apiInfo(otherInfo());

    }

    private ApiInfo otherInfo() {

        ApiInfo apiInfo = new ApiInfo("其它相关接口",//大标题

                "其它有关的接口，包括增加删除其它",//小标题

                "0.1",//版本

                "杭州",

                new Contact("zyx_other", "", ""),// 作者

                "点击",//链接显示文字

                ""//网站链接

        );

        return apiInfo;

    }

}

注:将SwaggerConfig在Spring注入管理 <bean class="com.demo.config.SwaggerConfig"/>

    增加几个@Bean，将会有几个选项（针对不同功能类别，可增加）

@ApiModel(value = "用户信息")

public class UserVo {

    @ApiModelProperty(value = "用户id", required = true)

    private long userId;

    @ApiModelProperty(value = "昵称", required = true)

    private String userName;

    public long getUserId() {

        return userId;

    }

    public void setUserId(long userId) {

        this.userId = userId;

    }

public String getUserName() {

return userName;

}

public void setUserName(String userName) {

this.userName = userName;

}

}

 此项增加注解配置，可方便在swagger上理解实体属性意义;

注：

增加接口中文名称

在class上增加标签@Api(tags="enterprise")

@Api(tags="enterprise")
public class EnterpriseController extends BaseController{

在SwaggerConfig类中，更新如蓝色字体

@Bean
public Docket cmsApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("cms")
.select()
.apis(RequestHandlerSelectors.basePackage("com.lc.cms.web.controller")).paths(PathSelectors.any()) // 对所有路径进行监控
.build()
.apiInfo(cmsInfo())
.tags(new Tag("asset","资产方法"),getTags());
}

private ApiInfo cmsInfo() {
ApiInfo apiInfo = new ApiInfo("后台运营接口", // 大标题
"后台运营接口", // 小标题
"2.0", // 版本
"www.91licheng.cn", new Contact("licheng", "", "zyx@91licheng.cn"), // 作者
"", // 链接显示文字
""// 网站链接
);
return apiInfo;
}

private Tag[] getTags() {
Tag[] tags = {
new Tag("merchant", "商户端方法"),
new Tag("assetPackage", "理财产品方法"),
new Tag("invest","投资方法"),
new Tag("repayment", "还款方法"),
new Tag("assetImage", "资产图片"),
new Tag("assetFile", "资产文件"),
new Tag("raise", "募集方法"),
new Tag("enterprise", "企业管理相关接口方法"),
new Tag("department", "部门相关接口方法"),
new Tag("employees", "员工相关接口方法"),
new Tag("salary", "薪资相关接口方法")
};
return tags;
}

4. 界面展示

 

 

在浏览器输入地址：http://localhost:8080/swagger-ui.html