使用Swagger在SpringBoot项目中管理API文档(使用Oauth2)

原创 2016年08月04日 14:23:10
1 、修改pom.xml引入swagger
      <!-- Swagger begin -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- Swagger end -->

2、SwaggerConfig.java
import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.PathSelectors.ant;
import java.util.List;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.OAuthBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationCodeGrant;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.GrantType;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.service.TokenEndpoint;
import springfox.documentation.service.TokenRequestEndpoint;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.ApiKeyVehicle;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * SwaggerConfig
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${security.userOauth.clientId}")
private String authClientId;

@Value("${security.userOauth.clientSecret}")
private String authClientSecret;

@Value("${security.userOauth.type}")
private String type;

@Value("${security.userOauth.authorizationUrl}")
private String authorizationUrl;

@Value("${security.userOauth.tokenUrl}")
private String tokenUrl;

@Value("${security.userOauth.tokenName}")
private String tokenName;

@Value("${security.userOauth.scope.code}")
private String scopeCode;

@Value("${security.userOauth.scope.desc}")
private String scopeDesc;

@Value("${app.key}")
private String appKey;

@Value("${app.name}")
private String appName;

@Value("${app.desc}")
private String appDesc;

@Value("${app.version}")
private String appVersion;

@Value("${app.termsOfServiceUrl}")
private String termsOfServiceUrl;

@Value("${app.contact.name}")
private String contactName;

@Value("${app.contact.url}")
private String contactUrl;

@Value("${app.contact.email}")
private String contactEmail;

@Value("${app.license}")
private String license;

@Value("${app.licenseUrl}")
private String licenseUrl;

/**
* Api分组,可以定义多个组
*/
@Bean
public Docket jackApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("jack")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("net.jack.lt"))
.build()
.securitySchemes(newArrayList(oauth()))
.securityContexts(newArrayList(securityContext()))
.apiInfo(jyxApiInfo());
}

private ApiInfo jyxApiInfo() {
ApiInfo apiInfo = new ApiInfo(appName, appDesc, appVersion, termsOfServiceUrl, 
new Contact(contactName, contactUrl, contactEmail),
license, licenseUrl);


return apiInfo;
}

@Bean
SecurityScheme apiKey() {
       return new ApiKey(appName, appKey, "header");
}


@Bean
SecurityContext securityContext() {
AuthorizationScope[] scopes = new AuthorizationScope[]{new AuthorizationScope(scopeCode, scopeDesc)};

SecurityReference securityReference = SecurityReference
.builder()
.reference(type)
.scopes(scopes)
.build();


return SecurityContext
.builder()
.securityReferences(newArrayList(securityReference))
.forPaths(ant("/api/**"))
.build();
}

@Bean
SecurityScheme oauth() {
return new OAuthBuilder()
.name(type)
.grantTypes(grantTypes())
.scopes(scopes())
.build();
}

List<AuthorizationScope> scopes() {
return newArrayList(new AuthorizationScope(scopeCode, scopeDesc));
}

List<GrantType> grantTypes() {
List<GrantType> grants = newArrayList(new AuthorizationCodeGrant(
new TokenRequestEndpoint(authorizationUrl, authClientId, authClientSecret),
new TokenEndpoint(tokenUrl, tokenName)));
return grants;
}

@Bean
public SecurityConfiguration securityInfo() {
return new SecurityConfiguration(authClientId, authClientSecret, scopeCode, 
appKey, appKey, ApiKeyVehicle.HEADER, "", ",");
}
}

3、在RESTful接口上添加注解@ApiOperation @ApiParam
     /**
 * 药品产品列表获取接口
 * pageNo 第几页
 * rows 每页条数
 * @return
 */
@RequestMapping(value = "/products", method = RequestMethod.GET)
@ApiOperation(value = "药品产品列表获取接口", notes = "可指定页码及每页条数")
@ResponseBody
public DrugProducts getDrugProductList(
@ApiParam(value="第几页") @RequestParam(required=false) Integer pageNo, 
@ApiParam(value="每页条数") @RequestParam(required=false) Integer rows) {
     }
或者
     @RequestMapping(value = "/hello", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value="问好", notes="向你问好")
@ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "第几页", required = false,
                dataType = "int", paramType = "query", defaultValue = "0"),
        @ApiImplicitParam(name = "count", value = "每页行数", required = false,
                dataType = "int", paramType = "query", defaultValue = "30"),
        @ApiImplicitParam(name = "name", value = "姓名", required = false,
                dataType = "string", paramType = "query", defaultValue = "")
})

public CommonParam hello(HttpServletRequest request) {

CommonParam commonParam = new CommonParam();
commonParam.setId(1);
commonParam.setName(request.getParameter("name"));
return commonParam;
}

4、在application.properties或application.yml中增加配置项
security.userOauth.clientId=swagger-ui
security.userOauth.clientSecret=Sa0rk3kgx
security.userOauth.type=oauth2
security.userOauth.authorizationUrl=http://dev.jyx365.top/sso/login
security.userOauth.tokenUrl=http://dev.jyx365.top/oauth/access_token
security.userOauth.tokenName=access_token
security.userOauth.scope.code=userinfo
security.userOauth.scope.desc=用户信息
app.key=learning
app.name=每日一学
app.desc=每日一学RESTful
app.version=0.1
app.termsOfServiceUrl=http://blog.csdn.net/jacktonny1
app.contact.name=闫不由衷
app.contact.url=http://blog.csdn.net/jacktonny1
app.contact.email=hulala208@126.com
app.license=The Apache License, Version 2.0
app.licenseUrl=http://www.apache.org/licenses/LICENSE-2.0.html

或 application.yml
security:
  userOauth:
    clientId: swagger-ui
    clientSecret: Sa0rk3kgx
    type: oauth2
    authorizationUrl: http://dev.jyx365.top/sso/login
    tokenUrl: http://dev.jyx365.top/oauth/access_token
    tokenName: access_token
    scope:
      code: userinfo
      desc: 用户信息
app:
  key: learning
  name: 每日一学
  desc: 每日一学RESTful
  version: 0.1
  termsOfServiceUrl: http://blog.csdn.net/jacktonny1
  contact:
    name: 闫不由衷
    url: http://blog.csdn.net/jacktonny1
    email: hulala208@126.com
  license: The Apache License, Version 2.0
  licenseUrl: http://www.apache.org/licenses/LICENSE-2.0.html


5、http://localhost:端口号/swagger-ui.html


SpringBoot集成Quartz实现定时器

SpringBoot+Quartz实现定时器, 由于本人也是刚学习,不足之处请各位大神指正 .. 1.pom配置 dependency> groupId>org.spri...

选择多张图片上传显示,并且删除。

简单的说就是把选择的图片转换成bitmap 并存入集合。然后给GrideView设置数据并显示。 直接代码走起来 这是主要的act/** * 需求是要求最多三个图片 * Created by BJ...

SpringBoot中使用Swagger生成RESTful规范API文档

Swagger是为了描述一套标准的而且是和语言无关的REST API的规范。对于外部调用者来说,只需通过Swagger文档即可清楚Server端提供的服务,而不需去阅读源码或接口文档说明。 官方网站...

Spring Boot中使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这...

Spring Boot中使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这...

Spring Boot中使用Swagger2构建API文档

程序员都很希望别人能写技术文档,自己却很不愿意写文档。因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码...
  • kai_16
  • kai_16
  • 2017年08月06日 16:38
  • 92

使用Swagger2构建强大的RESTful API文档

本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合...
  • cxhtgm
  • cxhtgm
  • 2017年11月27日 13:08
  • 127

Spring Boot学习(五)之使用Swagger2构建强大的RESTful API文档

随着前后端的分离,接口文档变的尤其重要,今天我们来说一说用SWAGGER2,来风骚的生成api文档。配置很简单,废话少说,直接上代码: pom.xml文件 01 parent> ...

Spring Boot中使用Swagger2构建强大的RESTful API文档

 由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的...

微服务架构 - Spring Boot中使用Swagger2构建强大的RESTful API文档

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:使用Swagger在SpringBoot项目中管理API文档(使用Oauth2)
举报原因:
原因补充:

(最多只允许输入30个字)